简介这份资源面向希望在 Visual Studio Code 中高效调试 TypeScript 的开发者尤其适合刚接触 TS 调试配置、需要快速跑通断点调试流程的初中级前端或 Node.js 工程师。包内共 10 个文件以 5 个 json 配置、2 个 ts 源码为主另含 license、md 说明与 gitignore压缩包约 5KB体积轻量便于直接解压复用。内容围绕 tsconfig.json 编译选项、.vscode/launch.json 调试配置、sourceMap 源码映射、断点设置与 Chrome 前端调试等关键环节展开并附带 watch、Call Stack、Scope、Console 等进阶调试视图的使用思路可帮助读者理解从编译到调试的完整链路。目前已有 1971 人学习下载适合作为 TypeScript 调试配置的参考模板对照自身项目快速搭建可用的调试环境并排查常见问题。1. 在 VS Code 里调试 TypeScript为什么你的断点总是不生效很多人第一次在 VS Code 里调试 TypeScript都会遇到同一个场景代码里点好红点按下 F5程序跑起来了断点却变成空心灰圈旁边飘一句 “Breakpoint set but not yet bound”。这不是玄学而是 TypeScript 调试链路里最典型的错位——你调试的是编译后的 JavaScript而 VS Code 默认把断点打在了源码上两边没对上。这个标题要解决的就是这件事让 VS Code 里的 TypeScript 断点真正停下来能看调用栈、能看变量、能单步。它适合三类人刚配好tsconfig.json想验证逻辑的前端写 Node 服务端脚本、想摆脱console.log的后端以及用 React TypeScript 做组件调试、却总在浏览器 DevTools 和编辑器之间来回切的人。核心不是装插件而是把 sourcemap、launch 配置、运行时三者的关系理顺。2. 先把调试链路拆开sourcemap、launch.json 与运行时2.1 TypeScript 调试到底在调试什么TypeScript 本身不能直接被 Node 或浏览器执行它要先编译成 JavaScript。所以调试时真正运行的是.js文件而你在.ts文件里打断点中间必须有一座桥这座桥就是 sourcemap。VS Code 的调试器通过 sourcemap 把运行时的 JS 行号映射回 TS 源码行号断点才能落到正确位置。理解这一点后面所有配置都顺了。tsconfig.json里的sourceMap: true负责生成.js.mapoutDir决定编译产物放哪launch.json里的program或preLaunchTask决定启动哪个文件、要不要先编译。三者任意一环缺失断点就会失效。常见做法是让outDir和源码目录分离比如src进dist出避免编译产物污染源码树。还有一个容易被忽略的点inlineSources和sourceRoot。如果你把编译产物部署到别的机器再调试sourcemap 里如果只存了相对路径映射就会断。本地开发一般不用管但一旦涉及容器或远程这两个字段值得检查。2.2 最小可用的 tsconfig 与 launch.json先给一份我平时起步用的tsconfig.json重点看sourceMap、outDir、rootDir三个字段{ compilerOptions: { target: ES2020, module: commonjs, rootDir: ./src, outDir: ./dist, sourceMap: true, strict: true, esModuleInterop: true, skipLibCheck: true }, include: [src/**/*.ts] }rootDir告诉编译器源码根在哪outDir是产物目录sourceMap打开映射。module选commonjs是因为 Node 默认调试场景下最省事如果你用 ESM后面会单独说坑。接着是.vscode/launch.json这是 VS Code 调试的入口配置{ version: 0.2.0, configurations: [ { name: Debug TS Node, type: node, request: launch, program: ${workspaceFolder}/src/index.ts, preLaunchTask: tsc: build, outFiles: [${workspaceFolder}/dist/**/*.js], sourceMaps: true, console: integratedTerminal } ] }这里有几个参数必须说清楚。program指向 TS 入口VS Code 会结合outFiles去找对应的编译产物preLaunchTask绑定一个 VS Code task在启动前先跑编译outFiles是告诉调试器去哪里找.js和.js.mapsourceMaps: true显式开启映射。console选integratedTerminal是为了让readline、process.stdin这类交互正常选默认的internalConsole有时会卡住。对应的.vscode/tasks.json里要有一个tsc: build任务{ version: 2.0.0, tasks: [ { label: tsc: build, type: shell, command: npx tsc -p tsconfig.json, problemMatcher: [$tsc], group: { kind: build, isDefault: true } } ] }problemMatcher用$tsc能把编译错误直接标到编辑器里省得你去终端翻。到这里一个最小的 Node 端 TypeScript 调试链路就通了。按 F5断点应该能实心停住。2.3 用 ts-node 跳过编译步骤的取舍如果你嫌每次改代码都要等tsc可以用ts-node直接跑 TS。配置改成这样{ name: Debug TS with ts-node, type: node, request: launch, runtimeArgs: [-r, ts-node/register], args: [${workspaceFolder}/src/index.ts], sourceMaps: true, cwd: ${workspaceFolder}, console: integratedTerminal }runtimeArgs里的-r ts-node/register让 Node 在启动时注册 ts-node 的 loaderargs直接传 TS 入口。这种方式省掉了preLaunchTask和outFiles启动更快。代价是 ts-node 默认不做类型检查要加--type-check或 TS_NODE_TYPE_CHECK而且大型项目里首次加载会慢。我的习惯是小脚本、临时验证用 ts-node正式项目、需要断点稳定复现的还是走tsc outFiles这条老路。3. 浏览器端与 React 项目的调试配置3.1 Chrome DevTools 协议下的 TS 断点前端项目里TypeScript 经过打包器webpack、vite处理后sourcemap 由打包器生成不再是tsc直接产出。这时launch.json要用chrome类型{ name: Debug React TS in Chrome, type: chrome, request: launch, url: http://localhost:3000, webRoot: ${workspaceFolder}/src, sourceMapPathOverrides: { webpack:///./src/*: ${webRoot}/* } }webRoot告诉调试器源码根目录sourceMapPathOverrides是解决路径对不上的后悔药。webpack 生成的 sourcemap 里路径常带webpack:///./src/前缀和本地实际路径不一致断点就会灰。不同脚手架前缀不同vite 常见的是webpack:///src/或直接相对路径配错了就打开 DevTools 的 Sources 面板看映射后的文件路径长什么样照着改。3.2 React 组件里断点打在哪一层React TypeScript 调试有个特殊问题你在组件函数里打断点命中的可能是 React 内部的renderWithHooks调用栈里全是框架代码。想只看自己的逻辑有两个办法。一是用条件断点右键断点选 “Edit Breakpoint”写条件比如props.id 42二是在launch.json里加skipFilesskipFiles: [ node_internals/**, ${workspaceFolder}/node_modules/** ]skipFiles让调试器单步时跳过这些路径调用栈干净很多。注意别把node_modules全跳过有时你需要看某个库内部行为临时在设置里关掉即可。3.3 用 VS Code 内置 JavaScript Debug Terminal 快速验证如果你不想写launch.jsonVS Code 有个内置的 JavaScript Debug Terminal。打开命令面板运行 “Debug: Create JavaScript Debug Terminal”然后在这个终端里直接node dist/index.js或npm run dev调试器会自动附加断点照样生效。这个方式适合临时排查尤其是你只想验证某一行逻辑、不想动项目配置的时候。缺点是每次都要手动开终端且不能保存成团队共享配置。我的用法是日常开发用launch.json临时救火用 Debug Terminal。4. 避坑与排查断点不生效的 5 个真实原因4.1 断点灰色sourcemap 没生成或路径不对现象断点是空心灰圈悬停提示 “Breakpoint set but not yet bound”。 原因tsconfig.json里sourceMap没开或者outFiles指向的目录里根本没有.js.map。 解决先确认dist目录下有.js.map文件没有就检查sourceMap: true和preLaunchTask是否真的跑了。有文件但还灰就在launch.json里加sourceMaps: true和outFiles并用trace: true打开调试日志看 VS Code 到底在找哪个路径。4.2 断点停在了编译后的 JS 文件里现象断点命中了但打开的是dist/index.js不是src/index.ts。 原因sourcemap 映射方向反了或者sourceMapPathOverrides没配。 解决检查tsconfig的rootDir和outDir是否对应浏览器端重点查sourceMapPathOverrides。Node 端如果用了ts-node确认sourceMaps为 true 且没有手动改process.env.NODE_OPTIONS覆盖掉。4.3 ESM 项目下__dirname报错、断点错位现象项目用module: ESNext或type: module调试时__dirname未定义断点行号偏移。 原因ESM 下没有__dirname且 Node 的 ESM loader 对 sourcemap 支持和 CommonJS 不同。 解决要么把调试目标切回 CommonJSmodule: commonjs要么在 ESM 里用import.meta.url配合fileURLToPath自己算目录。断点偏移通常是target设得太低导致编译产物行号变化大把target提到ES2020以上会缓解。4.4preLaunchTask没跑或跑失败调试的是旧代码现象改了 TS 代码断点行为没变变量还是旧值。 原因preLaunchTask配置的 label 和tasks.json里对不上或者tsc编译报错但调试照常启动。 解决在launch.json里加preLaunchTask: tsc: build后确认tasks.json里 label 完全一致把 task 的problemMatcher设成$tsc编译错误会直接弹出来。更稳妥的做法是给 task 加dependsOn或直接在preLaunchTask里用npx tsc --noEmit先做类型检查。4.5 条件断点写错导致永远不命中现象条件断点设了i 5但循环跑完都没停。 原因变量作用域不对或者条件表达式里用了 TS 类型断言运行时不存在。 解决条件断点里只能写运行时真实存在的变量不能写item as Foo这种。如果变量在闭包里确认断点位置在闭包内部。实在拿不准先打普通断点命中后在 Debug Console 里手动敲表达式验证。5. 进阶用 Debug Console 和日志断点替代 console.log5.1 Debug Console 里能做什么断点停住后VS Code 底部的 Debug Console 不只是看变量。你可以直接敲表达式比如JSON.stringify(obj, null, 2)、arr.filter(x x 10)甚至调用当前作用域里的函数。这比在代码里插console.log再删掉高效得多。注意 Debug Console 的执行上下文是当前暂停的栈帧切换调用栈帧后能访问的变量也会变。5.2 日志断点不暂停也能输出右键断点选 “Add Logpoint”输入比如i {i}, user {user.name}程序运行到这一行不会停但会在 Debug Console 打印。这相当于一个可随时开关、不污染源码的console.log。花括号里可以写任意表达式支持 TS 语法因为映射回源码后由调试器解析。我排查循环里的数据流时基本都用日志断点跑完一遍看输出比单步快得多。5.3 一个验证调试配置是否正确的检查清单检查项正确状态常见错误tsconfig的sourceMaptrue漏写或写成inline但outFiles没配outDir与outFiles路径一致outFiles指向src而非distpreLaunchTasklabel与tasks.json完全一致大小写或空格不一致断点颜色实心红空心灰说明未绑定调用栈文件显示.ts显示.js说明映射反了skipFiles跳过node_modules全跳过导致看不到库内部这张表我每次换新项目都会过一遍基本能覆盖九成配置问题。5.4 我自己的习惯我现在新开一个 TypeScript 项目第一件事不是写业务代码而是先把tsconfig、launch.json、tasks.json三个文件配好然后写一个index.ts打上断点跑一遍。确认断点实心、能停、调用栈显示.ts再开始写逻辑。这个习惯帮我省掉了无数次“以为是代码 bug、其实是调试没配对”的翻车。调试配置本身不产出功能但它决定了你后面排查问题的速度。希望帮到你。本文还有配套的精品资源点击获取