VSCode调试Node.js代码 开发者常用VSCode断点找Bug技巧

断点停在.js而非.ts的根本原因是source map未正确启用或路径未对齐；需在tsconfig.json设"sourceMap": true，在launch.json配"sourceMaps": true、"outFiles"及"resolveSourceMapLocations"。

想在VSCode里丝滑调试Node.js？光点一下那个小红点可不够。断点位置不对、配置没到位、source map没生效，任何一个环节出问题，都足以让你困在编译后的dist/index.js里，面对一堆_a、_b的变量名束手无策。真正高效的调试，建立在对调试器与Node.js运行时协作机制的透彻理解之上。

为什么断点总停在 .js 文件而不是 .ts？

这大概是TypeScript开发者最常遇到的调试困境：你明明在src/index.ts里信心满满地设下断点，一运行，调试器却精准地停在了dist/index.js的第12行，源码逻辑面目全非。

• 问题的核心在于，VSCode无法将运行时的Ja vaScript行号映射回你编写的TypeScript源码。这通常意味着sourceMaps没有正确启用，或者映射路径对不上。
• 首先，确保TypeScript编译器（tsc）在编译时生成了对应的.map文件。检查tsconfig.json，在compilerOptions里必须有这一行："sourceMap": true。
• 光有.map文件还不够，VSCode的调试器也需要知道怎么用它们。打开.vscode/launch.json，在对应的调试配置中，必须显式开启："sourceMaps": true，并告诉调试器编译后的文件在哪："outFiles": ["./dist/**/*.js"]。
• 如果你的项目结构更复杂，比如采用了Monorepo多包结构（像packages/cli/src这样），事情会麻烦一点。你还需要添加"resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]这个配置。否则，VSCode很可能因为找不到对应路径而直接跳过source map的解析。

如何让断点只在特定条件触发？

遇到那种循环到第100次才出现的诡异错误，或者只想在某个API返回null时才暂停检查？如果每次循环都停，效率就太低了。这时候，条件断点（Conditional Breakpoint）就是你的救星。

• 设置方法很简单：在已有的断点上右键，选择“编辑断点”，然后输入一个Ja vaScript表达式，比如i === 100或者response == null。
• 这里有个关键限制：表达式只能引用当前作用域内可访问的变量，不能调用函数（比如isValid()），也不能访问未声明的变量。如果表达式无效，断点会变成空心圆点，不会触发。
• 编写表达式时，注意运算符优先级和边界情况。例如，i == 100 && user.id !== undefined通常比i == 100 && !user.id更安全，因为后者在user.id为0或空字符串""时也会被判定为真，可能导致误触发。
• 如果设置了条件断点但没生效，而VSCode底部状态栏又显示「调试正在运行」，别急。打开「调试控制台」看看，那里通常会有明确的警告信息，比如Condition not valid: i === 100，能帮你快速定位问题。

require() 加载的模块里打不了断点？

有没有试过在第三方库的源码里打断点，比如node_modules/lodash/fp/map.js？点了红点，运行时代码却毫无停顿。这不是你的代码没执行到，而是VSCode“贴心”地帮你跳过了。

• 这个默认行为由launch.json中的skipFiles配置控制。它通常默认包含了["/**", "**/node_modules/**"]，意思就是跳过Node.js内部模块和所有node_modules里的文件。
• 当你确实需要深入调试某个依赖的内部逻辑时（比如怀疑axios的重试机制有bug），可以修改这个配置。最直接的方法是删除或注释掉skipFiles字段，或者将其设置为空数组："skipFiles": []。
• 更精细的做法是只排除你确定不需要调试的部分，比如保留跳过Node内部模块，但允许调试node_modules："skipFiles": ["/**"]。
• 需要注意的是，放开对node_modules的调试限制后，首次启动调试时可能会变慢一些，因为调试器需要加载和分析更多的符号信息。

Attach 模式下连不上正在运行的 Node 进程？

对于已经运行起来的Node进程，比如通过npm run dev启动的本地服务，或者跑在Docker容器里的应用，无法直接用Launch模式启动调试。这时候必须使用Attach模式去连接，而连接失败往往是让人最头疼的一步。

• 第一步，确认目标Node进程确实开启了调试端口。启动命令应该是node --inspect-brk index.js（使用--inspect-brk会在脚本第一行就暂停，比--inspect更利于连接）。
• 第二步，检查端口号是否匹配。launch.json中Attach配置的"port": 9229，必须和Node进程启动时--inspect指定的端口一致；如果启动时没指定，默认就是9229。
• 在Docker环境下，问题往往出在网络上。配置中的address不能是"localhost"，需要改成"0.0.0.0"。同时，启动容器时必须暴露调试端口，例如-p 9229:9229。
• 对于使用Windows WSL的开发者，还有一个经典陷阱：Node进程运行在WSL子系统中，而VSCode运行在Windows主机上。这时，address需要填写WSL子系统的IP地址（例如172.28.1.1），而不是localhost。

说到底，调试的难点往往不在于代码逻辑本身，而在于调试器与运行时之间那份“看不见的契约”。source map的路径对不对、调试端口有没有暴露、变量作用域能否被正确求值——这些细节就像精密仪器上的螺丝，任何一个没拧紧，整个调试流程就可能失灵。把这些关节打通，断点才能真正成为你洞察代码的“眼睛”。