如何在VSCode中调试Node.js应用程序【教程】

vscode调试node.js断点失效主因是launch.json未正确指向实际JS入口文件。需确保program路径为${workspaceFolder}相对路径、sourceMaps开启，typescript项目须编译或配置ts-node，Web服务推荐attach模式配合–inspect-brk。

VSCode 调试 Node.js 应用不依赖外部工具，只要项目结构规范、启动方式明确，开箱即用。关键不是“能不能”，而是“怎么配对 launch.json 的 program 和运行时入口”。

为什么 node 启动正常但 VSCode 断点不生效

最常见原因是调试配置没指向实际执行的 JS 入口文件，而是误配了 package.json 中的 start 脚本（比如 ts-node src/index.ts），但 VSCode 默认调试器只认纯 javaScript。

• 确认你真正运行的是哪个文件：用 node src/index.js？还是 npm start？后者需在 launch.json 中设 runtimeExecutable 指向 npm，并用 runtimeArgs 传 ["run", "start"]
• 若用 TypeScript，必须先编译出 .js 文件，或改用 ts-node：在 launch.json 中设 "runtimeExecutable": "npx"，"runtimeArgs": ["ts-node", "src/index.ts"]
• 检查 sourceMaps 是否开启：TypeScript 项目需在 tsconfig.json 中含 "sourceMap": true，且 launch.json 中设 "sourceMaps": true

launch.json 中 program 路径写相对还是绝对

必须写相对于 workspaceFolder 的相对路径，VSCode 不解析环境变量或波浪号（~）。

• 错误写法："program": "/home/user/myapp/src/index.js"（硬编码路径，换机器就崩）
• 正确写法："program": "${workspaceFolder}/src/index.js"（${workspaceFolder} 是唯一可靠占位符）
• 如果入口是 dist/index.js，确保该文件存在——调试器不会自动触发 build，得手动先运行 npm run build 或在 preLaunchTask 中配置

调试 express/Koa 等 Web 服务时端口被占用或无法热重载

VSCode 默认 attach 模式（attach）比 launch 模式更适合长期运行的服务，尤其配合 nodemon。

• 用 nodemon --inspect-brk 启动：如 nodemon --inspect-brk=9229 src/index.js，然后在 launch.json 中选 Attach to Node Process 配置，port 设为 9229
• --inspect-brk 比 --inspect 更稳妥：它会在第一行暂停，确保断点来得及注册
• 不要在 launch.json 里同时配 program 和 attach；二者互斥，混用会导致调试器连不上或报 Cannot connect to runtime process

真正的难点不在配置本身，而在于搞清「当前到底是谁在跑代码」——是 node 直接执行？npm 转发？nodemon 包裹？还是 ts-node 解释？每种角色对应不同的 launch.json 字段组合，漏掉一个字段（比如忘了 sourceMaps 或写错 outFiles）就会让断点静默失效。