如何利用vscode的断点与调试器调试Node.js应用【教程】

vs code node.js 调试需正确配置 launch.json 和运行环境：Launch 模式要求 program 指向可执行入口，Attach 模式需端口与地址匹配；typescript 项目须启用 sourcemaps、生成 .map 文件并配置 outFiles 和 resolveSourceMapLocations；调试第三方模块需调整 skipFiles 或启用 smartStep；ESM 项目需添加 runtimeArgs 支持。

VS Code 的 Node.js 调试器不是“开箱即用”的魔法，它依赖正确的启动配置和运行环境匹配；直接点断点却无法命中，绝大多数情况是 launch.json 中的 program 路径没指向源码入口，或用了转译（如 TypeScript、ESM）却没配好 outFiles 或 resolveSourceMapLocations。

断点不触发？先确认调试会话是否真的连上了 node.js 进程

VS Code 调试器必须连接到一个启用了 inspector 协议的 Node.js 进程。本地开发时常见两种模式：

• Launch 模式：VS Code 启动 Node.js，并自动附加调试器 —— 要求 launch.json 中 program 是你项目的入口文件（如 ./src/index.js），且该文件能被 Node 直接执行（非 TS/JSX/ESM 语法需先编译）
• Attach 模式：Node.js 已在运行（如 node --inspect-brk ./dist/index.js），VS Code 主动连接 —— 此时必须确保 port 一致（默认 9229），且 address 是 localhost（docker 容器内运行需设为 0.0.0.0 并暴露端口）

验证是否连上：看 VS Code 底部状态栏是否显示「调试正在运行」，或打开「调试控制台」查看是否有类似 Debugger attached. 的日志。

用 TypeScript 写的项目，断点总停在 .js 文件里

这是 source map 映射失败的典型表现。VS Code 默认不会自动解析 .ts → .js 的映射关系，除非你明确告诉它去哪里找源码和 map 文件。

• 确保编译时生成了 .map 文件（tsc --sourceMap 或 tsconfig.json 中 "sourceMap": true）
• 在 launch.json 中启用 sourceMaps: true，并设置 outFiles 指向编译输出目录（如 ["./dist/**/*.js"]）
• 如果 .ts 文件不在项目根目录下（比如在 packages/foo/src），还需加 resolveSourceMapLocations 排除无关路径："resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]

不配 outFiles，VS Code 就不知道该把 dist/index.js 的哪一行映射回 src/index.ts —— 断点只能停在 JS 上。

require() 加载的模块里打不了断点？检查 skipFiles 和 smartStep

VS Code 默认跳过 node_modules 和内置模块（lib/internal 等），所以你在 node_modules/lodash/index.js 里打的断点永远不会触发。

• 如确需调试第三方模块源码（比如想确认某个 bug 是否出在依赖里），在 launch.json 中删掉或注释掉 skipFiles 字段，或将其设为空数组："skipFiles": []
• 但更推荐的做法是：把模块软链进 node_modules 并启用 smartStep: true，它会让调试器自动跳过未有源码映射的代码行，避免卡在 require 或 promise 内部
• 注意：若模块是 ESM 格式且你用的是 CommonJS 入口，可能因加载机制差异导致断点失效 —— 此时应统一模块系统，或改用 node --loader ts-node/esm 启动

最常被忽略的一点：VS Code 调试器对 ESM 支持仍有限制。如果你用 type: "module" + .mjs 或顶层 await，launch.json 必须显式指定 runtimeArgs：["--experimental-specifier-resolution=node"]，否则断点可能在 import 语句前就中断，甚至根本无法启动进程。