如何在 VSCode 中验证 Node 环境是否成功安装与配置

在VSCode中配置Node.js环境时，几个常见问题经常让人头疼，尤其是刚接触开发环境配置的小伙伴。这里把几个最典型的坑点梳理出来，顺便说说对应的解决方案，希望对你有帮助。

node -v 在系统终端报 command not found 怎么办

这说明 Node.js 压根没进系统 PATH，后续在 VSCode 里的一切操作都注定失败。先别急着打开 VSCode，老老实实回到系统原生命令行——Windows 的 CMD 或 PowerShell，macOS 或 Linux 的 Terminal——输入 node -v 和 npm -v 验证一下。

如果报错，常见原因无非这么几个：

• Windows 安装时忘记勾选 Add Node.js to PATH；解决办法很简单，重装 Node.js 并务必勾选这个选项
• macOS 或 Linux 用户用 brew install node 安装的，但 which node 输出的路径（比如 /opt/homebrew/bin/node）没有写进 ~/.zshrc 或 ~/.bash_profile
• 安装路径包含空格或中文字符（比如 C:\Program Files\nodejs 或 D:\软件\nodejs），导致 PATH 解析失败；建议重装到纯英文且无空格的路径，比如 C:\nodejs

VSCode 终端里 node -v 正常，但 npm install 报错或卡住

这说明环境变量已经继承过来了，但 npm 本身的配置可能没生效。重点检查两个地方：

• npm config get registry 返回的是否是国内镜像地址（比如 https://registry.npmmirror.com），而不是 https://registry.npmjs.org
• npm config get prefix 返回的全局路径是否已经加入系统 PATH——尤其是 Windows 用户，改了 prefix 却忘了同步更新环境变量，这种情况非常常见
• 改完配置后，记得关掉所有 VSCode 窗口再重新打开；内置终端不会自动 reload shell 配置，这是很多人忽略的细节

launch.json 调试时提示 “Cannot find runtime 'node'”

VSCode 调试器找不到 node 可执行文件，并不是因为 Node.js 没装，而是它没按你预期的路径去寻找。根本原因在于：runtimeExecutable 字段为空时，VSCode 会用自己的逻辑去查 PATH，这和你在终端里看到的 which node 结果可能不一致。

解决办法是在 .vscode/launch.json 的配置里显式指定路径：

{
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "/usr/local/bin/node",
  "program": "${file}"
}

Windows 用户填绝对路径，比如 "runtimeExecutable": "C:\\nodejs\\node.exe"；macOS 或 Linux 用户用 which node 输出的真实路径。验证方法：在代码里加一行 console.log(process.execPath)，对比输出是否和 runtimeExecutable 一致。

Code Runner 插件运行 JS 文件报 Cannot use import statement outside a module

这不是环境问题，而是执行方式不匹配项目模块类型。Code Runner 默认用 node xxx.js 来执行，完全忽略了 package.json 里的 "type": "module" 或 "exports" 声明。

正确的做法是：

• 禁用 Code Runner，直接用 VSCode 内置终端执行：node index.js
• 如果项目是 ESM，确保入口文件扩展名是 .mjs，或者 package.json 中有 "type": "module" 声明
• 调试时用 launch.json，而不是按 Code Runner 的 Ctrl+Alt+N 快捷键

最后还有一个最容易被忽略的细节：VSCode 终端是否真正加载了你的 shell 配置。哪怕 npm config get registry 在系统终端里是对的，在 VSCode 终端里返回空值或旧值，说明它没读 ~/.zshrc。此时手动执行 source ~/.zshrc，或者彻底重启 VSCode，才能解决问题。