VSCode调试Node.js失败90%因node未被识别：macOS/Linux需从终端执行code .启动以加载shell配置，Windows需确保安装时勾选“Add to PATH”或手动添加路径；program必须指向真实JS文件如"${workspaceFolder}/src/index.js"，TS项目需编译后指向dist或配ts-node，ESM项目须在package.json声明"type": "module"。
VSCode 调试 Node.js 程序失败，90% 不是配置写错了，而是 node 命令根本没被 VSCode 找到——它不继承你的 shell 环境变量，也不读你安装时勾选的 PATH。先确认终端里 node -v 能跑，再动 launch.json。
node 命令在 VSCode 终端里报 command not found
这不是插件问题，也不是 launch.json 写得不够漂亮，而是 VSCode 启动方式绕过了 shell 初始化文件。
- macOS/Linux：从 Dock 或 Spotlight 启动 VSCode，不会自动执行
~/.zshrc或~/.bash_profile；必须在终端里运行code .启动 - Windows：安装 Node.js 时没勾选 “Add to PATH”，或装在非默认路径（比如
C:\Program Files\nodejs\），需手动加进“系统变量”的PATH - 验证方式唯一：打开 VSCode 内置终端（
Ctrl + `），输入node -v和npm -v，有输出才算过关 - 用
nvm的用户，要确保当前 shell 已加载nvm.sh，且 VSCode 是从该终端启动的；否则可在.vscode/settings.json中硬编码："runtimeExecutable": "/Users/you/.nvm/versions/node/v18.17.0/bin/node"
launch.json 的 program 字段总指向错误路径
断点灰掉、提示 Cannot launch program，基本就是 program 没指向一个真实存在的 .js 文件。
- 正确写法：
"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 项目调试时报 Cannot use import statement outside a module
这不是语法错误，是 Node 默认按 CommonJS 解析，遇到 import 就崩。模块类型没对齐。
- 必须在项目根目录
package.json中显式声明："type": "module" - 如果用
code-runner插件，需手动改其executorMap：把javascript对应值设为"node --experimental-specifier-resolution=node $fileName" - VSCode 调试器（
pwa-node）也依赖这个"type"值；没声明就强行import，断点可能命中但require()会失败，process.cwd()行为也可能异常
用 nodemon 或 ts-node 调试时断点失效
这类工具接管了启动流程，VSCode 默认的 launch 模式无法稳定注入调试逻辑，强行配 runtimeExecutable 容易断连或跳过断点。
-
nodemon：不要让program直接指向它；改用request: "attach"，先手动运行nodemon --inspect-brk ./bin/www，再在 launch.json 中配好port连上去 -
ts-node：优先走runtimeExecutable + runtimeArgs方式，而不是把它当普通可执行文件塞进program - Express/Koa 类服务更推荐
attach模式：先node --inspect-brk ./bin/www启动，再附加调试，避免EADDRINUSE和环境变量错位
真正容易被忽略的是：VSCode 的调试器不关心你用什么框架或构建工具，只认两个东西——node 是否可用，以及 program 是否指向一个能被 Node 直接执行的 .js 文件。其他所有配置，都是在这两个前提成立之后才生效的。
