tsconfig.json中baseUrl和paths配置错误会导致VSCode路径跳转失效、智能提示退化为any、import报“Cannot find module”；需确保baseUrl为"./"、paths值以"./"开头且为数组、重启TS Server，并检查moduleResolution和类型定义完整性。
tsconfig.json里baseUrl和paths配错，路径跳转和补全就断了
VSCode 的 TypeScript 语言服务依赖 tsconfig.json 中的 baseUrl 和 paths 来解析别名导入（如 import utils from "@utils/helper"）。如果配置不合法或路径未对齐，类型检查会退化为 any，跳转失效，智能提示也只显示基础语法。
常见错误现象包括：
- 点击别名路径无反应，或跳转到错误文件
- 补全时看不到模块导出的类型或函数
- 状态栏显示 TypeScript 版本正常，但
import行下有红色波浪线，提示“Cannot find module”
实操建议：
-
baseUrl必须是相对于tsconfig.json所在位置的有效目录，通常设为"./"；设成"src"却没加./前缀会导致解析失败 -
paths的 key 是带通配符的模式（如"@utils/*"），value 必须是数组，且每个路径要以./开头，例如["./src/utils/*"]，不能写成["src/utils/*"] - 确保项目根目录下存在
tsconfig.json，且不是放在子目录里——否则 VSCode 不会加载它 - 改完后必须重启 TS Server：按
Ctrl+Shift+P→ 输入TypeScript: Restart TS Server
VSCode没用工作区TypeScript版本，新语法直接不识别
即使 tsconfig.json 配置正确，如果 VSCode 正在用内置 TypeScript（比如 5.2），而项目本地装的是 5.4，那么像 const x = { a: 1 } satisfies SomeType 这类新特性就无法被识别，补全缺失、类型推断异常，甚至整个文件被标记为“no implicit any”警告泛滥。
实操建议：
- 点击右下角 TypeScript 版本号，确认当前选中的是
Use Workspace Version，不是Bundled - 检查项目
node_modules/typescript是否存在，运行npx tsc --version验证版本一致性 - 在
.vscode/settings.json中显式指定路径："typescript.tsdk": "./node_modules/typescript/lib"，避免因多层嵌套 workspace 导致自动检测失败 - 如果项目使用 pnpm，注意
node_modules/.pnpm/typescript@...路径结构不同，tsdk应指向实际lib目录，可用pnpm ls typescript查看真实路径
路径映射生效了，但智能提示仍不显示导出内容
路径映射只是让导入能解析，不代表类型定义能被索引。很多情况下，模块本身没有提供类型（比如纯 JS 库），或 index.d.ts 缺失、未被 types 字段声明，VSCode 就只能看到 any，补全自然为空。
实操建议：
- 对第三方库，先查是否提供官方类型：
npm view axios types，返回undefined就得手动装@types/axios - 对本地别名模块，确保其入口文件（如
src/utils/index.ts）有明确的export，而不是仅const+export default混用导致类型丢失 - 检查
tsconfig.json中是否漏掉"moduleResolution": "node"—— 没它，TS Server 不会按 node_modules 规则查找@types或types字段 - 运行
npx tsc --noEmit --watch观察终端报错，比 VSCode 界面提示更早暴露路径或类型缺失问题
文件监视器爆满，路径跳转延迟甚至完全卡住
当项目含大量嵌套目录（比如自动生成的文档、测试快照、node_modules 残留），VSCode 的文件监视器会耗尽操作系统句柄限额，导致语言服务器收不到文件变更通知——此时哪怕 tsconfig.json 完美、版本匹配，路径跳转也会变慢或失效，补全响应延迟数秒。
实操建议：
- 在终端执行：
find . -type d | awk -F'/' '{print NF-1}' | sort -nr | head -n 3，查看最深的三个目录层级，重点检查是否为构建产物或缓存目录 - 在
.vscode/settings.json中加强files.watcherExclude，至少包含："**/node_modules/**"、"**/dist/**"、"**/build/**"、"**/__snapshots__/**" - 避免把整个磁盘根目录或用户主目录作为 VSCode 工作区打开——监视范围过大极易触发上限
- Windows 用户若用 WSL，注意
/mnt/c/...路径的监视性能极差，应将项目放在/home/xxx下再打开
路径映射和智能提示是耦合的两层：前者解决“能不能找到”，后者依赖“能不能分析”。很多人调通了 paths 就以为万事大吉，却忽略了类型服务是否真正加载了目标文件——尤其是当目录被 watcherExclude 错误排除后，VSCode 根本不会去解析那些 ts 文件，自然也不会提供任何提示。
