简介：这份资源面向希望在 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.map；outDir决定编译产物放哪；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.map；sourceMaps: 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 的 loader，args直接传 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里加skipFiles：

"skipFiles": [ "<node_internals>/**", "${workspaceFolder}/node_modules/**" ]

skipFiles让调试器单步时跳过这些路径，调用栈干净很多。注意别把node_modules全跳过，有时你需要看某个库内部行为，临时在设置里关掉即可。

3.3 用 VS Code 内置 JavaScript Debug Terminal 快速验证

如果你不想写launch.json，VS 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 不同。 解决：要么把调试目标切回 CommonJS（module: 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.log

5.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 一个验证调试配置是否正确的检查清单

这张表我每次换新项目都会过一遍，基本能覆盖九成配置问题。

5.4 我自己的习惯

我现在新开一个 TypeScript 项目，第一件事不是写业务代码，而是先把tsconfig、launch.json、tasks.json三个文件配好，然后写一个index.ts打上断点跑一遍。确认断点实心、能停、调用栈显示.ts，再开始写逻辑。这个习惯帮我省掉了无数次“以为是代码 bug、其实是调试没配对”的翻车。调试配置本身不产出功能，但它决定了你后面排查问题的速度。希望帮到你。

本文还有配套的精品资源，点击获取