tsconfig.json 中 baseUrl 和 paths 必须配对使用，且需重启 TS 服务、确保文件被正确识别、tsc --noEmit 无报错，否则 VSCode 别名跳转失效。

tsconfig.json 里 compilerOptions.baseUrl 和 compilerOptions.paths 必须配对使用

VSCode 的 TypeScript 语言服务依赖 tsconfig.json 中的路径映射配置才能识别别名并支持跳转。只写 paths 不设 baseUrl，或者 baseUrl 设成 "." 却没把 tsconfig.json 放在项目根目录，都会导致跳转失效。

常见错误现象：写了 {"@utils/*": ["src/utils/*"]}，但 Ctrl+点击 @utils/xxx 没反应，或提示 “No definition found”。

• baseUrl 必须是相对于 tsconfig.json 所在目录的相对路径，通常设为 "./" 或 "src"
• paths 的 key 是匹配模式（支持通配符），value 是相对于 baseUrl 的数组，必须用字符串数组形式，哪怕只有一个路径
• 如果项目有多个 tsconfig.json（如 tsconfig.json 和 tsconfig.test.json），确保你编辑的是被 VSCode 实际加载的那个——可通过右下角 TypeScript 版本旁的文件路径确认

VSCode 需要重启 TS 服务或重新打开文件夹才能生效

改完 tsconfig.json 后，VSCode 不会自动重载路径映射。直接保存文件，跳转依然无效是正常现象。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 快捷键 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（Mac），输入 “TypeScript: Restart TS server”，回车执行
• 或者关闭当前文件夹，再通过 “File → Open Folder…” 重新打开项目根目录
• 不推荐仅靠关闭/重开单个文件，TS 语言服务是进程级缓存，单文件刷新不触发路径解析重载

别名跳转失败时先检查 tsc --noEmit 是否报错

VSCode 的跳转能力底层复用 TypeScript 编译器的模块解析逻辑。如果 tsc 命令本身都解析不了别名，VSCode 肯定也跳不了。

在终端运行：

tsc --noEmit

，观察是否报错，典型问题包括：

• error TS6059: File 'xxx' is not under 'rootDir'：说明 baseUrl 或 paths 指向了 include 或默认包含范围之外的目录，需同步调整 include 数组
• error TS2307: Cannot find module '@utils/xxx'：路径映射语法写错，比如漏了尾部 /*，或 value 路径不存在
• 没有报错但跳转仍无效？可能是当前打开的文件未被 TS 服务纳入——检查文件右下角是否显示 “TypeScript”，而不是 “Plain Text” 或 “JavaScript”

注意 jsconfig.json 对 JS 文件的影响

如果你在纯 JavaScript 文件（.js 或 .jsx）里也想用相同别名跳转，VSCode 默认不会读 tsconfig.json。此时需要额外提供 jsconfig.json，且内容不能照搬：

• jsconfig.json 中 compilerOptions.moduleResolution 必须设为 "node"（TS 默认就是，JS 默认不是）
• baseUrl 和 paths 可以完全复用，但整个文件需是合法 JSON，不能含注释、尾逗号等 TS 允许但 JSON 不允许的语法
• 如果项目混用 TS/JS，建议统一用 tsconfig.json 并通过 allowJs: true + checkJs: true 管理 JS 文件，避免双配置不同步

路径别名跳转看着简单，真正卡住人的往往不是配置写法，而是 TS 服务没重载、当前文件没被识别为 TS 上下文、或者 tsc 自身就解析失败——遇到跳不动，先跑命令，再看服务状态，比反复改 paths 更省时间。