Node.js调试失效首要排查node命令是否可用，再检查launch.json中program路径是否正确、TypeScript需编译后调试、Express推荐attach模式、source map需配置outFiles和resolveSourceMapLocations。
Node.js 调试不生效？先确认 node 命令在终端可用
VSCode 的 Node.js 调试器本质是调用系统已安装的 node，不是自带运行时。如果终端里输 node -v 报“command not found”，调试必失败——launch.json 再配得漂亮也没用。
常见错误现象：Cannot find runtime 'node' on PATH 或断点全灰、不触发、控制台无输出。
- Mac/Linux：检查
which node是否有输出；若用nvm，确保当前 shell 已加载（比如source ~/.nvm/nvm.sh），且 VSCode 是从该终端启动的（code .） - Windows：确认 Node.js 安装时勾选了 “Add to PATH”，或手动把
C:\Program Files\nodejs\加进系统环境变量 - 重启 VSCode —— 环境变量变更后，VSCode 不会自动刷新 PATH
launch.json 里 program 路径写错是最常见的断点失效原因
program 必须是相对于工作区根目录的**可执行入口文件路径**，不是文件夹、不是 node_modules/.bin 下的软链、也不能是带空格未转义的路径。
使用场景：调试本地脚本、CLI 工具开发、Express 启动文件等。
- 正确写法：
"program": "${workspaceFolder}/src/index.js"（推荐用变量，避免硬编码） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 找不到） - 错误写法：
"program": "./src/index.js"（.在这里不被解析，等同于字面量） - 如果入口是 TypeScript，别直接指向
.ts文件——除非你配了preLaunchTask编译，否则会报Cannot launch program because corresponding JavaScript cannot be found
调试 Express/Koa 项目时，attach 模式比 launch 更稳
launch 模式要接管整个进程启动，而 Express 默认监听端口、可能 fork 子进程、或依赖环境变量（如 NODE_ENV），稍有不一致就卡住或报 EADDRINUSE。用 attach 让你先手动跑起来，再连上去，更贴近真实运行态。
性能影响：几乎无——只是调试器连接方式不同，不影响代码执行。
- 先在终端运行：
node --inspect-brk ./bin/www（注意加--inspect-brk让它停在第一行） -
launch.json配置关键项："type": "node"、"request": "attach"、"port": 9229（默认端口，和--inspect一致） - 如果改过端口（比如
--inspect=9230），port值必须同步改，否则连不上 - 不要同时开两个
--inspect进程，端口冲突会导致第二个报Could not connect to debug target
源码映射（source map）没生效？检查 outFiles 和 resolveSourceMapLocations
TypeScript 或 Webpack 构建项目里，断点打在 .ts 文件却跳到编译后的 .js，说明 source map 没被正确识别。VSCode 不自动猜路径，靠配置显式声明。
兼容性影响：旧版 VSCode（resolveSourceMapLocations 支持弱，建议保持 outFiles 明确。
- TS 项目常用配置：
"outFiles": ["${workspaceFolder}/dist/**/*.js"]，确保和tsconfig.json的outDir一致 - Webpack 项目若用
devtool: 'source-map'，且 map 文件和 js 同目录，可以加："resolveSourceMapLocations": ["${workspaceFolder}/**"] - 如果 source map 是内联（
//# sourceMappingURL=data:application/json;base64,...），无需额外配置，但构建慢、体积大 - 验证是否生效：在调试时打开「调试」侧边栏 → 「已加载脚本」，看有没有展开出
.ts文件节点
复杂点在于，source map 路径可能是相对路径、绝对路径、甚至带 webpack:// 协议，而 VSCode 只认本地文件系统路径。一旦 sources 字段里出现无法映射的路径，断点就只能挂在 js 上——这点很容易被忽略，直到你发现 ts 断点全失效才回头查 map 文件内容。
