vscode调试node.js失败90%因node未被识别：先验证内置终端node -v是否有输出，无则说明path未继承（macos/linux需从终端code .启动，windows需确保安装时勾选add to path并配置系统环境变量），再配launch.json。
VSCode 调试 Node.js 项目失败，90% 的问题不是配置写错了，而是 node 命令根本没被 VSCode 看到——先验证这个，再动 launch.json。
终端里 node -v 有输出，但 VSCode 里报 command not found: node
这不是插件或设置问题，是 VSCode 启动时没加载 shell 的环境变量初始化文件（比如 ~/.zshrc 或 ~/.bash_profile）。
- macOS/Linux：从 Dock 或 Spotlight 启动 VSCode 不会读
~/.zshrc；改完 PATH 后只source ~/.zshrc不够，必须彻底退出 VSCode，再在终端执行code .启动项目 - Windows：Node.js 安装时若没勾选
Add to PATH，系统级环境变量里就没有C:\Program Files\nodejs\；打开“系统属性 → 高级 → 环境变量”，把该路径加进“系统变量”的PATH，然后重启 VSCode - 验证方式唯一：在 VSCode 内置终端（
Ctrl + `）里运行node -v—— 没输出就别往下配，全是空转
launch.json 里 program 字段总填错
这个字段是调试器找入口的唯一依据，填错就直接报 Cannot find module 或静默退出。
- 单文件临时调试用
"program": "${file}"（注意不是${fileBasename}） - 后端项目务必显式写绝对路径，比如
"program": "${workspaceFolder}/src/server.js"，且确保该文件真实存在 - TypeScript 项目：
program必须指向编译后的.js文件（如dist/server.js），不能指src/server.ts；同时tsconfig.json中要启用"sourceMap": true，且.js.map和.js在同一目录 - ESM 项目：
package.json必须含"type": "module"，否则调试器按 CommonJS 解析，import报错、路径也容易错乱
断点打了却不停，或者调试控制栏灰掉
大概率是 request 类型或工作区状态不对，而不是代码逻辑问题。
- 确认
launch.json里"request": "launch"（启动模式）或"request": "attach"（附加模式）与实际使用场景匹配；比如用nodemon --inspect-brk启动，就得配request: "attach"，不能硬塞runtimeExecutable指向nodemon - 加
"cwd": "${workspaceFolder}"显式声明工作目录，避免require('./config')因路径解析失败而报Cannot find module - ESM 项目调试时，建议在
env里加"NODE_OPTIONS": "--enable-source-maps"，否则源映射可能失效 - 如果用了
ts-node，别用type: "node"，改用type: "pwa-node"，并配"runtimeExecutable": "npx"和"runtimeArgs": ["ts-node", "${file}"]
别用 code-runner 插件跑带 process.stdin 或 ESM 的脚本
它默认命令极简：node $fileName，不处理编码、模块类型、输入流，也不读 package.json 配置。
- Windows 中文路径乱码：在 VSCode 设置中搜
code-runner.executorMap，把javascript对应值改成："node -r utf-8 $fileName" - ESM 报
Cannot use import statement outside a module：确保package.json有"type": "module"，再把 executor 改成："node --experimental-specifier-resolution=node $fileName" - 遇到
process.stdin就假死：这是code-runner的固有限制，它不支持交互式输入；换用内置终端手动运行，或直接用 F5 调试模式
真正卡住人的地方，往往不是 launch.json 多复杂，而是 node 是否被正确继承、program 是否指向可执行的 JS 文件、以及模块解析模式是否和项目实际一致——这三个点对不上，所有断点都是摆设。
