如何设置VSCode中前端项目路径别名？

本文共计835个文字，预计阅读时间需要4分钟。

VSCode 本身不读取 Webpack 或 Vite 的 resolve.alias，仅认可 jsconfig.json 或 tsconfig.json 中的 compilerOptions.paths。光配置构建工具，Ctrl+Click 依赖功能仍然无效。

jsconfig.json 或 tsconfig.json 必须存在且位置正确

VSCode 只在项目根目录下查找这两个文件，子目录里的配置会被忽略。如果你用的是纯 JavaScript 项目（没用 TypeScript），就创建 jsconfig.json；否则用 tsconfig.json。

• baseUrl 必须设为 "."（不是 "./src" 或 "src"），它表示“从配置文件所在目录开始解析”
• paths 的 key 必须带通配符 *，比如 "@/*" 才能匹配 @/components/Button；写成 "@/components/*" 就只能匹配 @/components/xxx，无法覆盖 @/utils
• 值数组里的路径是相对于 baseUrl 的，所以 "@/*": ["src/*"] 是对的，"@/*": ["./src/*"] 会报错

最小可用配置示例：

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }

配置完必须重启 TypeScript 服务

VSCode 不会自动监听 jsconfig.json 变更。改完文件后，不手动触发，跳转和补全依旧不生效。

立即学习“前端免费学习笔记（深入）”；

• 快捷键：Ctrl + Shift + P → 输入 TypeScript: Restart TS Server → 回车
• 也可以关闭 VSCode 再打开，但重启服务更快
• 如果项目里有 node_modules/@types 或自定义类型声明，重启还能解决部分 Cannot find module 报错

Webpack/Vite 别名必须和 paths 完全一致

编辑器能跳转 ≠ 代码能运行。构建工具和语言服务的别名规则一旦不一致，就会出现“Ctrl+Click 成功，但打包时报 Module not found”。

• Vite 项目：在 vite.config.ts 的 resolve.alias 里写 { '@': path.resolve(__dirname, 'src') }
• Webpack 项目：在 webpack.config.js 的 resolve.alias 里写 { '@': path.resolve(__dirname, 'src') }
• 注意：Vite/Webpack 的 alias 值是绝对路径，而 paths 的值是相对路径 —— 但语义要严格对应，"@/*": ["src/*"] 对应 @ → src 目录

别名跳转失败时优先检查这三处

90% 的跳转失败问题都出在这几个地方，不用急着装插件。

• 项目根目录下有没有 jsconfig.json 或 tsconfig.json？内容是否包含 baseUrl 和 paths？
• VSCode 右下角状态栏是否显示 “TypeScript language features” 已启用？没启用说明 TS 服务没起来
• 当前打开的文件是否在 include 范围内？比如 include: ["src/**/*"] 但你正在编辑 tests/xxx.js，那它就不受路径映射影响

真正麻烦的不是配置本身，而是 paths 和 resolve.alias 这两套规则必须时刻对齐 —— 改一个，另一个漏了，问题就藏得特别深。