真正搭好 Node 运行环境需满足：能执行 node 命令且 VSCode 可断点调试；node -v 和 npm -v 必须在全新系统终端中成功运行，否则因 PATH 未配置导致调试失败；launch.json 中 program 必须指向真实入口文件，TypeScript 项目需 sourceMap 与路径严格匹配；ESM 项目避免 CommonJS 混用；重启 VSCode 确保环境变量生效。
能跑 node 命令，且 VSCode 能断点调试，才算真正搭好了 Node 运行环境——其余全是可选项。
node -v 和 npm -v 在系统终端报错，VSCode 就不可能调通
这不是 VSCode 的问题，而是 Node.js 没进系统 PATH。Windows 安装时漏勾 Add to PATH 是最常见原因；macOS/Linux 用 nvm 的话，source ~/.nvm/nvm.sh 必须写进 shell 配置（如 ~/.zshrc），且新终端要重开才能生效。
- 验证方式：关掉所有 VSCode 窗口，打开全新系统终端（不是 VSCode 内置终端），执行
node -v和npm -v - Windows 路径别含中文或空格（如
D:\我的项目\nodejs），否则npm可能静默失败 -
npm -v成功是硬门槛——VSCode 调试器底层靠它启动脚本，不成功就直接挂
launch.json 里 program 字段填错，断点永远不命中
默认生成的 "program": "${file}" 只适合单文件调试；实际项目几乎都用 package.json 的 main 或 scripts.start 入口，必须显式指向真实路径。
- 正确写法示例：
"program": "${workspaceFolder}/src/index.js"或"program": "${workspaceFolder}/dist/app.js" - 如果入口是 TypeScript 编译后产物，确保
sourceMaps开启且outDir路径匹配 - 别把
runtimeExecutable和program搞混：runtimeExecutable是 node 可执行文件路径（极少需设），program是你要运行的 JS 文件路径
想调试 npm start 或 nodemon？不能直接 launch，得换模式
VSCode 调试器不支持热重载进程替换。直接在 launch.json 里设 "program": "npm" + "args": ["start"] 会卡住或无输出——必须用 console: "integratedTerminal" 才能看到日志，但依然无法断点。
- 调试
npm start：改用"type": "node"+"request": "launch"，再设"runtimeExecutable": "npm"和"runtimeArgs": ["run", "start"] - 调试
nodemon：只能用 attach 模式——先终端执行nodemon --inspect-brk index.js，再在launch.json中配"request": "attach"和对应"port"（默认9229） - attach 模式下务必确认
localRoot和remoteRoot一致，否则源码映射失效，断点变灰
断点失效却没报错？大概率是 type 写成大写或 sourceMap 没对齐
VSCode 对 launch.json 的字段大小写敏感："type": "Node" 或 "type": "NODE" 都会静默降级为普通运行，不进调试流程。
- 必须写成小写：
"type": "node" - TypeScript 项目中，
tsconfig.json的sourceMap和outDir必须与launch.json中的program和outFiles路径严格对应 - ESM 项目（
package.json含"type": "module"）若用 CommonJS 式 require，会触发Cannot find module——这不是环境问题，是模块系统冲突
最常被忽略的其实是调试器启动那一刻的上下文：它继承的是 VSCode 启动时加载的 PATH，而不是你后来在终端里手动 export 的变量。所以哪怕 node -v 在内置终端能跑，调试器仍可能找不到 node——重启 VSCode 才是最简单的验证手段。
