VSCode启用TypeScript需三要素齐备：项目根目录存在有效tsconfig.json、右下角状态栏选择“Use Workspace Version”、每次修改配置后执行“TypeScript: Restart TS server”；缺一则出现tsc报错但编辑器不提示、路径别名跳转失效、“无法找到模块”等典型问题。
VSCode 里 TypeScript 不是“装了就自动好用”，而是必须有 tsconfig.json、用对 TypeScript 版本、且 TS Server 重启过，三者缺一不可——否则你会遇到编辑器不报错但 tsc 编译失败、路径别名跳转失效、import 提示“无法找到模块”等典型症状。
必须在项目根目录放一个有效的 tsconfig.json
VSCode 只在工作区根目录发现 tsconfig.json 时，才启用完整类型检查；没有它，只做基础语法高亮。空文件 {} 都比没有强，但推荐直接写最小可用配置：
-
"target": "ES2020"和"lib": ["ES2020"]要配对，Node.js 项目别加"dom" -
"module": "NodeNext"（ESM 项目）或"commonjs"（CJS），不能和"moduleResolution"冲突 -
"strict": true必须开，否则any泛滥、未初始化属性无提示 -
"include": ["src/**/*"]路径必须带引号、用正斜杠、结尾通配符不能漏 - 删掉所有 JSON 注释（
tsc --init生成的注释行会干扰部分工具）
确认 VSCode 正在用项目本地的 TypeScript 版本
VSCode 底部状态栏显示的 TypeScript 版本，决定它怎么解析代码。默认可能用内置旧版，导致和 npx tsc 行为不一致：
- 右下角点击 TypeScript 版本号 → 选 Use Workspace Version（前提是已
npm install --save-dev typescript） - 改完
tsconfig.json后，必须按Ctrl+Shift+P→ 输入TypeScript: Restart TS server手动重启 - 如果用了
pnpm或bun，VSCode 有时找不到本地typescript，可在设置里手动指定typescript.tsdk路径，例如./node_modules/typescript/lib
baseUrl + paths 配置不对，路径别名就永远跳转不了
VSCode 的 @/utils 这类别名跳转，完全不看 Webpack/Vite 配置，只认 tsconfig.json 里的映射规则：
-
"baseUrl": "./"是起点，不是"src"或"."（少点斜杠都不行） -
"paths": { "@/*": ["src/*"] }中，key 和 value 都必须以/*结尾；写成"@/": ["src/"]就无效 - 该配置默认只对
.ts文件生效；若想在.js里也用别名，得加"allowJs": true和"checkJs": true - 别名只影响类型检查和跳转，不影响运行时——运行时仍靠打包工具或 Node.js 的
exports字段
调试前必须校准 launch.json 的 outFiles 和 sourceMaps
VSCode 调试 TypeScript 源码，本质是靠 .js 文件里的 sourceMap 找回 .ts 原始位置。一旦路径或开关没对齐，断点就打不进：
-
"sourceMaps": true必须设为true（默认是true，但显式写出来更稳） -
"outFiles"要和tsconfig.json的outDir匹配，例如"outDir": "./dist"→"outFiles": ["${workspaceFolder}/dist/**/*.js"] -
"preLaunchTask"推荐设为"tsc: build - tsconfig.json"，确保每次调试前都编译最新代码 - 如果用
ts-node直接运行，launch.json类型应为"pwa-node"，且去掉outFiles，改用"runtimeArgs": ["-r", "ts-node/register"]
最容易被忽略的是：每次修改 tsconfig.json 后不重启 TS Server，VSCode 就不会重新加载配置；哪怕路径、字段全对，编辑器行为依然滞后。这不是缓存问题，是服务进程没刷新。
