VSCode调试Node.js失败主因是launch.json配置错误、node不在PATH或sourceMap未对齐；必须正确设置type:"node"、request:"launch"/"attach"、program指向可执行.js文件，且Node≥14、sourceMaps显式启用。
VSCode 本身不运行 Node.js，它只调用你系统里装好的 node；调试失败，90% 是因为 launch.json 配错、node 不在 PATH、或源码映射没对上——不是插件没装全。
launch.json 必须填对的三个字段
VSCode 不会猜你要跑哪个文件，也不会自动编译 TS 或识别 ESM。配置错一个字段，F5 就静默失败。
-
type必须是"node"（别写"pwa-node"，老项目或远程场景容易 fallback 失败） -
request填"launch"（启动新进程）或"attach"（连已有进程），漏掉任一字段整个配置无效 -
program必须指向可执行的.js文件：TS 项目填"${workspaceFolder}/dist/index.js"，不是src/index.ts；ESM 项目确认 Node ≥ 14 且没混用--loader和--inspect
断点不生效？先查 Node 版本和 --inspect 状态
断点变灰、hover 看不到变量、调用栈显示 eval 或乱路径，基本是调试协议没通。
- 终端执行
node -v，必须 ≥ 14（低于 14 的 async_hooks 支持不全，断点挂不住异步栈） - 别手动在
runtimeArgs里加--inspect：VS Code 会自动注入，重复加导致端口冲突，报错address already in use - 用
nodemon热重载时，不要把program改成nodemon路径；正确做法是设runtimeExecutable+runtimeArgs，例如："runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon"，"runtimeArgs": ["--inspect-brk", "${workspaceFolder}/index.js"]
TS/Webpack 项目调试时 sourceMap 找不到源码
VSCode 不读 tsconfig.json 里的 sourceMap: true，必须在 launch.json 显式告诉它去哪找原始代码。
- TS 项目：确保
tsconfig.json同时开启"sourceMap": true和"inlineSources": true（后者让源码嵌进 map，避免路径解析失败） -
launch.json中加"sourceMaps": true和"outFiles": ["./dist/**/*.js"]，若源码在子目录（如packages/foo/src），还要加"resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"] - Webpack 用户：
devtool设为"source-map"或"inline-source-map"，禁用"eval"类型（VS Code 不识别）
附加到已运行进程（attach 模式）连不上
常见于 npm run dev、Docker 或 PM2 场景，连不上基本是端口或地址不匹配。
- 终端启动命令必须带
--inspect=9230（显式指定端口），不能只写--inspect（默认 9229 容易被占） -
launch.json中"port"必须严格等于命令行里写的数字，比如"port": 9230 - Docker 或远程服务需设
"address": "0.0.0.0"（默认是"localhost"，容器内无法回环） - 多 Worker 或
fork()子进程调试，必须开"autoAttachChildProcesses": true，且主进程和子进程都用--inspect-brk，端口要唯一或留空让 Node 自选
最常被忽略的是：VSCode 启动方式继承的 PATH 可能和终端不一致，尤其 macOS/Linux 下用 zsh 启动 VSCode 时。改完 terminal.integrated.env.osx 后必须重启 VSCode，否则环境变量不生效。
