VSCode调试Node.js后端无需额外插件，只需node命令可用、launch.json中program指向真实可执行.js文件、Node版本≥14；失败主因是环境未加载、路径错误或sourceMap断链。
VSCode 调试 Node.js 后端不需要额外插件，只要 node 命令可用、launch.json 中 program 指向真实可执行的 .js 文件、Node 版本 ≥ 14，断点基本都能稳停；失败几乎都卡在环境没加载、路径写错、或源码映射断链上。
node 命令在 VSCode 终端里跑不通？不是插件问题，是 PATH 没继承
VSCode 调试器本质调用系统 node，不是自带运行时。终端里 node -v 报错，调试必挂。
- macOS/Linux：检查
~/.zshrc或~/.bash_profile是否导出 Node 路径（如export PATH="/opt/homebrew/bin:$PATH"），改完后source ~/.zshrc，再从该终端启动 VSCode（code .） - Windows：重装 Node.js，务必勾选 “Add to PATH”；或手动把
C:\Program Files\nodejs\加进系统环境变量 - VSCode 必须彻底退出再重开——改了环境变量它不会自动刷新
- 验证方式：打开 VSCode 内置终端（
Ctrl + `），执行node -v和npm -v，必须有输出
launch.json 的 program 字段写错，断点就永远灰掉
program 必须是能被 node 直接执行的 .js 文件路径，不是文件夹、不是 .ts、不是软链接、也不能是相对路径字面量。
- 正确写法：
"program": "${workspaceFolder}/src/index.js"（推荐用变量，跨平台安全） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 找不到） - 错误写法：
"program": "./src/index.js"（.在这里不解析，等同于字面字符串） - TypeScript 项目：别指
src/index.ts，要么配preLaunchTask编译到dist/，然后指dist/index.js；要么用runtimeExecutable: "npx"+runtimeArgs: ["ts-node", "src/index.ts"] - ESM 项目：确保
package.json里有"type": "module"，否则import会解析失败
断点变空心、hover 看不到变量？先查 source map 和 --inspect 模式
断点灰掉、调用栈显示 eval、路径乱码——调试器压根没定位到原始代码位置。
- Node 版本必须 ≥ 14（旧版不支持现代
--inspect协议） - TypeScript：确认
tsconfig.json开启"sourceMap": true和"inlineSources": true，且编译后.js.map和.js在同一目录 - Webpack/Babel：
devtool设为"source-map"或"inline-source-map"，禁用"eval"类型 - 用
nodemon？别直接改program指向nodemon脚本——会导致调试断连。正确做法是换runtimeExecutable+runtimeArgs，例如："runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon"，"runtimeArgs": ["--inspect-brk", "${workspaceFolder}/index.js"]
Express/Koa 这类 Web 框架，attach 模式比 launch 更可靠
launch 模式要接管整个进程启动，而 Express 常依赖环境变量、子进程、端口复用，稍有不一致就卡住或报 EADDRINUSE。
- 先在终端手动运行：
node --inspect-brk ./bin/www（注意加--inspect-brk让它停在第一行） -
launch.json配"request": "attach"，"port": 9229（若命令行指定了--inspect=9230，这里必须同步改成9230） - 不要同时开两个
--inspect进程——端口冲突会直接导致第二个连接失败 - 如果用
npm start启动，且脚本里是ts-node或babel-node，别硬套node类型调试器，改用"type": "pwa-node"+ 注册 loader
最常被忽略的是：VSCode 不会自动编译 TypeScript，也不会帮你 resolve ESM import，更不会替你处理 require('./config') 因 cwd 错误导致的模块找不到。这些不是“配置没选对”，而是运行时上下文本身就不一致——得靠 cwd、runtimeArgs、env 显式对齐。
