node环境配通需三步验证:终端中node -v/npm -v输出版本号;vscode完全重启后launch.json的program路径正确且指向可执行js文件;调试时runtimeexecutable与cwd明确指定,避免path歧义。

VSCode 里 node 命令能跑、断点能停、npm 不报错,才算 Node 环境真正配通——不是装完就完事,而是每一步都得验证到位。
终端里 node -v 报错?先别碰 VSCode 设置
这是 90% 配置失败的起点。VSCode 内置终端根本不会“自动继承”你改过的环境变量,它只读启动时的系统 PATH。
- 在系统终端(Windows PowerShell / macOS Terminal / Ubuntu GNOME Terminal)里直接运行
node -v和npm -v,必须输出版本号;否则 VSCode 所有后续操作都是空中楼阁 - Windows 安装时漏选
Add to PATH是最常见原因,重装 LTS 版并勾选此项,路径避开C:\Program Files\(含空格) - macOS/Linux 用
nvm的,确认which node输出的路径已写进~/.zshrc,且重启终端后生效 - 改完环境变量后,必须完全退出 VSCode(关掉所有窗口),再重新打开项目文件夹——仅“重载窗口”无效
launch.json 里 program 字段填错,断点永远不触发
VSCode 调试器只认 program 指向的文件,填错路径或类型,进程就静默启动或直接崩溃。
- 单文件调试用
"program": "${file}",不是${fileBasename}或${workspaceFolder} - 后端项目入口固定(如
src/server.js),必须写绝对路径:"program": "${workspaceFolder}/src/server.js" - TypeScript 项目,
program必须指向编译后的.js文件(如dist/server.js),且tsconfig.json中开启"sourceMap": true - ESM 项目(
"type": "module"在package.json中),确保文件扩展名是.mjs或明确声明,否则import会报ERR_REQUIRE_ESM
用了 nodemon 或 ts-node,别硬塞进 launch.json
VSCode 默认的 launch 模式无法稳定接管这类进程管理工具,强行配置 runtimeExecutable 只会让断点失效或连接中断。
- 要热重载调试,改用
attach模式:终端先执行nodemon --inspect-brk src/server.js,再在launch.json中新增一个"request": "attach"配置,连到默认端口9229 -
ts-node同理,终端跑ts-node --inspect-brk src/index.ts,调试器 attach 过去 - 不要在
launch.json里把"program"设为"nodemon"或"ts-node",这绕过了 VSCode 的源码映射机制
terminal.integrated.env.* 和 runtimeExecutable 是两套逻辑
你在终端里能跑 node,不代表调试器就一定用同一个 node——它们走的是不同路径。
- 终端 PATH 由
terminal.integrated.env.windows(或.linux/.osx)注入,用于所有终端命令 - 调试器用的
node由launch.json中的runtimeExecutable显式指定,不写就按系统 PATH 顺序找,可能和终端看到的不是同一个 - 验证方式:在代码里加
console.log(process.execPath),对比终端输出和调试器里打印的路径是否一致 - 多版本共存(比如
nvm切换)时,runtimeExecutable必须写死,不能依赖 PATH
最常被忽略的其实是工作目录:cwd 不设,默认从 VSCode 启动路径开始解析 require(),package.json 里的 exports 或 type 字段就可能失效。真要稳,"cwd": "${workspaceFolder}" 这一行别省。











