Node.js调试需正确配置--inspect-brk启动参数、launch.json及source map。推荐用node --inspect-brk或nodemon --inspect-brk启动，手动配置launch.json的type、runtimeExecutable、env和sourceMaps，确保TypeScript源码断点有效，排查时关注端口、nodemon版本与ts-node适配。
调试 Node.js 应用不是简单点个“运行”就完事，关键在配置准确、断点合理、环境一致。VSCode 自带的调试能力足够强大，但很多人卡在 launch.json 配置或启动方式上，导致断点不生效、变量看不到、甚至根本进不了调试模式。
确保 Node.js 启动方式支持调试
Node.js 从 v8.0+ 开始原生支持 --inspect 参数，这是 VSCode 调试的基础。直接用 node app.js 启动是无法被 VSCode 附加（attach）的。
- 开发时推荐用
node --inspect-brk app.js：加-brk会在第一行暂停，方便你提前设好断点 - 如果用
nodemon，加上--inspect-brk并传给 node：nodemon --inspect-brk app.js - 避免用
npm start直接启动——除非你在package.json的 script 里明确写了--inspect-brk
正确配置 .vscode/launch.json
不要依赖自动检测，手动创建 launch.json 更可靠。选择 “Node.js” 环境后，优先用 launch 类型（而非 attach），尤其适合从头启动的应用。
-
type: 必须是
node -
request:
launch（本地启动）或attach（连接已运行进程） -
runtimeExecutable: 如果用了 nvm 或多版本 Node，建议显式指定路径，比如
"${env:HOME}/.nvm/versions/node/v18.18.2/bin/node" -
env: 可添加
NODE_ENV: "development"等环境变量，和运行时保持一致 - 如果项目用 TypeScript，program 指向编译后的
./dist/index.js，并确保已先执行tsc
断点与调试体验优化
VSCode 调试器能读取 source map，但前提是构建工具（如 tsc、webpack、vite）生成了正确的 map 文件，并在 launch.json 中启用 sourceMaps: true。
- 在 TypeScript 源码里打断点，只要
sourceMaps: true且 map 文件存在，VSCode 会自动映射到运行时代码 - 右键断点可设置“条件断点”或“日志点”，比如输入
user.id === 123，只在特定数据下暂停 - 调试控制台（Debug Console）支持直接执行 JS 表达式，比如
console.log(req.url)或修改局部变量值（谨慎使用） - 遇到“断点未绑定”，先检查左下角是否显示 “Paused on debugger statement” 或 “Source maps loaded”，否则说明 map 未生效或路径不对
常见问题快速排查
90% 的调试失败都出在环境或配置错位，而不是代码本身。
-
端口被占？ 默认
--inspect使用 9229，可在参数中指定--inspect=9230，并在 launch.json 的port字段同步修改 -
nodemon 不触发断点？ 确保 nodemon 版本 ≥ 2.0，且命令中
--inspect-brk在app.js前面，例如：nodemon --inspect-brk --watch src -e ts --exec ts-node src/index.ts -
调试器连上了却看不到变量？ 检查是否启用了
skipFiles（默认跳过 node_modules），或尝试关闭 “Enable JavaScript Source Map Support” 再打开 -
ts-node + 调试不工作？ 推荐改用
ts-node --inspect-brk启动，并在 launch.json 中设置"runtimeArgs": ["--inspect-brk"]和"program": "${workspaceFolder}/src/index.ts"
基本上就这些。调试不是玄学，是配置、约定和工具链的配合。把启动参数、launch.json、source map 三者对齐，VSCode 就能稳稳帮你定位问题。
