简介这份资源面向希望在 Visual Studio Code 中高效调试 TypeScript 的开发者尤其适合刚接触 TS 调试配置、需要一份可运行参考工程的中级学习者。内容围绕 tsconfig.json 编译选项、.vscode/launch.json 调试配置、断点设置与 sourceMap 源码级调试展开并覆盖 Node 与 Chrome 两种调试场景帮助读者理解从编译到断点命中的完整链路。压缩包共 10 个文件以 5 个 json 配置与依赖清单、2 个 ts 示例源码为主另含 readme 说明、LICENSE 与 .gitignore整体约 5KB结构精简可直接作为调试模板复用。目前已有 1971 人学习下载。读者可据此快速搭建可调试的 TS 工程掌握 launch.json 关键字段含义、sourceMaps 关联原理及断点、调用栈、作用域等面板的使用思路减少自行摸索配置的时间成本。1. 在 VS Code 里调试 TypeScript为什么你的断点总是不生效很多人第一次在 VS Code 里调试 TypeScript都会遇到同一个场景辛辛苦苦在.ts文件里点了个红点按下 F5结果断点变成灰色空心圈程序直接跑完控制台连个停顿都没有。这不是玄学而是 TypeScript 调试链路里最典型的一环没打通——VS Code 调试的是运行时而 TypeScript 最终跑的是编译后的 JavaScript源码和产物之间需要一张 source map 来对齐。这个标题要解决的就是这件事让 VS Code 的调试器真正停在你的.ts源码行上而不是停在编译产物里更不是压根不停。它适合所有用 TypeScript 写 Node 服务、CLI 工具、脚本或者用 ts-node、tsx 直接跑代码的人。无论你是刚配好vscode环境的新手还是被baseUrl弃用警告、moduleResolutionnode10弃用提示折腾过的老手只要断点不生效这篇的排查路径都能用上。接下来从最小可跑配置讲起再拆参数、拆坑最后给一套能直接抄的 launch 配置。2. 先搞懂 VS Code 调试 TypeScript 的三种运行链路2.1 编译后调试最稳但最容易配错 source map最常见也最稳的做法是先用tsc把 TypeScript 编译成 JavaScript再让 VS Code 启动 Node 去跑产物。这条链路的关键在于编译时必须生成 source map且launch.json里的sourceMaps要打开outFiles要指向产物目录。很多人翻车就翻在outFiles写错或者tsconfig.json里sourceMap没开导致调试器找不到.ts和.js的映射关系。先看一份最小可用的tsconfig.json{ compilerOptions: { target: ES2022, module: commonjs, outDir: ./dist, rootDir: ./src, sourceMap: true, strict: true, esModuleInterop: true, skipLibCheck: true }, include: [src/**/*.ts] }这里每个参数都有明确作用。outDir决定产物落在哪rootDir决定源码根目录两者配合才能让 source map 里的相对路径正确。sourceMap: true是调试的命根子没有它断点必然灰。module: commonjs是 Node 默认能直接跑的形式如果你用 ESM 需要额外处理后面会讲。strict和esModuleInterop属于工程规范不影响调试但建议开。编译命令很简单npx tsc --watch--watch让 tsc 常驻改完.ts自动重编译调试时不用手动反复跑。接着是launch.json{ version: 0.2.0, configurations: [ { name: Debug TS (compiled), type: node, request: launch, program: ${workspaceFolder}/dist/index.js, preLaunchTask: tsc: build - tsconfig.json, outFiles: [${workspaceFolder}/dist/**/*.js], sourceMaps: true, console: integratedTerminal, skipFiles: [node_internals/**] } ] }program指向编译后的入口outFiles告诉调试器去哪找 source mapsourceMaps: true显式开启映射。preLaunchTask会在每次 F5 前先跑一次构建任务这个任务名要和.vscode/tasks.json里定义的一致否则会报找不到任务。skipFiles把 Node 内部文件排除在单步之外避免你按 F11 掉进node:internal里出不来。提示如果你用的是 monorepo 或产物目录不在distoutFiles一定要跟着改这是断点变灰的第一大原因。2.2 ts-node 直跑省掉编译但版本兼容是雷区不想每次编译可以用ts-node直接跑.ts。它的原理是在 Node 的 require 钩子里实时编译所以调试器看到的就是源码source map 由 ts-node 自己处理。配置上要装ts-node和typescript然后launch.json改成{ name: Debug TS (ts-node), type: node, request: launch, runtimeArgs: [-r, ts-node/register], program: ${workspaceFolder}/src/index.ts, sourceMaps: true, console: integratedTerminal, skipFiles: [node_internals/**] }runtimeArgs里的-r ts-node/register是关键它在 Node 启动时注册编译钩子。program直接指向.ts入口。这条链路省事但有两个边界一是 ts-node 对 ESM 和moduleResolution新选项的支持经常滞后二是大项目里实时编译会拖慢启动。如果你在tsconfig.json里用了moduleResolution: bundler或node16ts-node 可能直接报错这时候要么降级配置要么换 tsx。2.3 tsx 直跑目前对 ESM 和新配置最友好的选择tsx是基于 esbuild 的 TypeScript 运行时启动快对 ESM 支持好近两年在 Node 侧用得越来越多。配置和 ts-node 类似但更省心{ name: Debug TS (tsx), type: node, request: launch, runtimeExecutable: npx, runtimeArgs: [tsx, src/index.ts], sourceMaps: true, console: integratedTerminal, skipFiles: [node_internals/**] }注意这里用的是runtimeExecutable加runtimeArgs而不是program因为 tsx 是作为命令被调起的。sourceMaps: true依然要开。tsx 的好处是它不依赖tsconfig.json里的moduleResolution做运行时解析遇到baseUrl弃用、moduleResolutionnode10弃用这类警告时运行时层面不会直接崩但类型检查层面还是要在tsconfig里处理干净。三条链路怎么选小项目、快速验证用 tsx需要严格对齐生产编译产物用编译后调试老项目已经用 ts-node 且没踩到 ESM 坑就继续用。选型不是信仰问题是看你的tsconfig和 Node 版本能不能对上。3. launch.json 里那几个决定成败的参数3.1 sourceMaps、outFiles、resolveSourceMapLocations 的配合sourceMaps是总开关默认在type: node下其实是开的但显式写出来能避免被其他配置覆盖。outFiles只在编译后调试时需要它是一组 glob告诉调试器哪些.js文件带有可用的 source map。如果你把outFiles写成dist/*.js而实际产物在dist/sub/下断点就会灰。resolveSourceMapLocations是很多人不知道的后悔药。默认情况下调试器只会在outFiles匹配到的文件附近解析 source map。如果你用了路径别名或者 source map 里的sources指向了工作区外的路径就需要显式放开resolveSourceMapLocations: [ ${workspaceFolder}/**, !**/node_modules/** ]这行的意思是允许在工作区内解析 source map但排除node_modules。不加这个某些用paths别名或 pnpm 软链的项目会出现「源码能找到但断点不绑定」的怪现象。3.2 路径别名与 baseUrl 弃用后的正确写法热搜里提到的baseUrl已弃用、将在 TypeScript 7.0 停止运行这不是小事。以前大家习惯写{ compilerOptions: { baseUrl: ./src, paths: { utils/*: [utils/*] } } }现在baseUrl被标记弃用推荐直接用paths配合相对tsconfig的解析。新写法是去掉baseUrlpaths里的目标相对于tsconfig.json所在目录{ compilerOptions: { paths: { utils/*: [./src/utils/*] } } }但这里有个调试层面的坑TypeScript 编译时能解析别名Node 运行时不一定认。编译后调试时产物里的require(utils/foo)会直接报模块找不到。解决办法有两个一是用tsc-alias在编译后把别名替换成相对路径二是在launch.json里加NODE_PATH或使用module-alias。我一般用tsc-alias在构建脚本里加一步npx tsc npx tsc-aliastsc-alias会读取tsconfig的paths把产物里的别名改写成真实相对路径这样 Node 运行时和调试器都能对上。3.3 moduleResolution 弃用警告怎么处理才不影响调试moduleResolutionnode10的弃用警告同样来自 TypeScript 新版本。node10就是老的node解析策略现在推荐node16、nodenext或bundler。如果你把moduleResolution改成node16module通常也要跟着改成node16这会引入 ESM/CJS 的互操作规则调试链路可能整个变样。稳妥的迁移顺序是先确认运行时是 CJS 还是 ESM。CJS 项目可以暂时保留node10并接受警告或者升到node16但把module也设为node16同时确保package.json里没有type: module。ESM 项目则用nodenext并且launch.json里要改用 tsx 或 Node 的--loader方案。不要只改moduleResolution不改module这会让编译产物和运行时解析规则打架断点绑定失败只是表象真正的问题是模块加载路径全乱。注意弃用警告本身不影响运行但 TypeScript 7.0 之后会变成错误。现在不改将来升级就是硬中断建议在调试配置稳定后单独排期迁移。4. 断点不生效、路径对不上、源码找不到的排查清单4.1 断点变灰先查 source map 有没有生成现象.ts里断点是灰色空心圈鼠标悬停提示「Breakpoint set but not yet bound」。原因调试器没有找到该.ts对应的 source map或者outFiles没匹配到产物。解决先确认tsconfig.json里sourceMap: true再跑一次npx tsc去dist目录看有没有.js.map文件。有 map 文件后检查launch.json的outFiles是否覆盖到该产物。如果产物在dist/src/index.js而outFiles写的是dist/*.js改成dist/**/*.js。最后确认program指向的入口和实际运行入口一致。4.2 断点停在了编译后的 JS 里现象断点命中了但打开的是dist/index.js不是src/index.ts。原因source map 的sources路径和调试器解析出的路径不一致常见于rootDir没设或设错。解决在tsconfig.json里显式设置rootDir: ./src保证 source map 里的相对路径从src开始。如果已经编译过删掉dist重新编译旧 map 可能残留错误路径。另外检查launch.json有没有开sourceMaps以及resolveSourceMapLocations是否把源码目录排除了。4.3 路径别名导致运行时模块找不到现象编译通过调试启动时报Cannot find module utils/foo。原因TypeScript 的paths只影响类型检查和编译期解析Node 运行时按真实文件路径找模块不认别名。解决用tsc-alias在编译后重写路径或在launch.json里通过env注入NODE_PATH指向产物根目录。前者更干净后者在 monorepo 里容易出边界问题。如果用的是 tsx它内部会处理一部分别名但tsconfig里的paths仍要写对。4.4 preLaunchTask 找不到或构建失败现象按 F5 弹窗提示「Could not find the task tsc: build」。原因launch.json里preLaunchTask的名字和tasks.json里定义的不一致或者根本没建tasks.json。解决在.vscode/tasks.json里定义同名任务或者把preLaunchTask去掉改成手动先跑tsc --watch。我一般保留preLaunchTask因为能保证每次调试前产物是最新的但任务名必须一字不差。VS Code 自动生成的tsc: build - tsconfig.json任务名可以直接用前提是工作区根目录有tsconfig.json。4.5 ESM 项目下 require 报错现象package.json里有type: module调试启动报require is not defined或ERR_REQUIRE_ESM。原因编译后调试默认按 CJS 启动 Node但产物是 ESM或者 ts-node 的 register 钩子不支持 ESM。解决ESM 项目优先用 tsx 调试它的runtimeArgs方式对 ESM 友好。如果坚持编译后调试launch.json里要加runtimeArgs: [--experimental-vm-modules]或改用 Node 的--loader并且tsconfig的module设为node16或nodenext。这条链路最复杂建议先在小 demo 上跑通再迁到主项目。5. 让调试配置可复用的几个进阶习惯5.1 用条件断点和日志点替代 console.log断点打多了单步会变成体力活。VS Code 支持条件断点右键断点选「Edit Breakpoint」输入表达式比如i 100或user.id targetId只有条件为真才停。日志点更省事右键选「Add Logpoint」输入当前 i 的值是 {i}运行时会在调试控制台打印而不暂停。这两个功能在循环和热点路径里能省掉大量console.log的增删也避免改代码引入新问题。5.2 多配置并存一个 launch.json 覆盖三种链路实际项目里经常需要同时保留编译后调试和 tsx 直跑。launch.json的configurations是数组可以放多份用name区分。按 F5 时在调试面板下拉选择即可。我一般放三份Debug TS (compiled)、Debug TS (tsx)、Debug Current File。最后一份用${file}作为program适合临时调试单个脚本{ name: Debug Current File, type: node, request: launch, runtimeExecutable: npx, runtimeArgs: [tsx, ${file}], sourceMaps: true, console: integratedTerminal }${file}是 VS Code 预定义变量指向当前打开的文件。这样不用为每个脚本单独写配置临时验证一段逻辑时特别顺手。5.3 验证调试配置是否真的对齐源码配好之后怎么确认断点真的绑到了.ts一个简单办法是在launch.json里临时加trace: true启动后会在调试控制台输出 source map 解析过程能看到调试器把哪个.js映射到了哪个.ts。如果输出里出现source map not found或路径明显不对就能顺着定位。另一个办法是在.ts里断点命中后看调用栈面板顶部显示的文件名是不是.ts如果是.js说明映射没生效。我自己的习惯是每换一个项目先花十分钟把tsconfig的rootDir、outDir、sourceMap和launch.json的program、outFiles、sourceMaps这六个点对一遍再开始写业务代码。这十分钟能省掉后面无数次「断点为什么又灰了」的返工。调试配置不是一次配好就永远不管的东西TypeScript 版本升级、模块解析策略迁移、Node 版本切换都会让它失效把它当成工程配置的一部分定期检查比出问题再翻文档高效得多。希望帮到你。本文还有配套的精品资源点击获取