如何配置VSCode以支持TypeScript开发？

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

在VSCode中配置TypeScript并非装了就好，需要以下几个关键步骤：

必须在项目根目录放一个有效的 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 就不会重新加载配置；哪怕路径、字段全对，编辑器行为依然滞后。这不是缓存问题，是服务进程没刷新。