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 语句前就中断，甚至根本无法启动进程。
