在VSCode中建立稳定的Node环境

在 VSCode 里配置 Node.js 开发环境，看似简单——装个 Node、装个 VSCode，就能开始写代码。但真正动手的人都知道，这里头有不少坑。最核心的判断标准其实就一条：能跑 node -v 和 npm -v，且 VSCode 内置终端、调试器都能直接调用，才算真正稳定。其余什么插件、格式化、TypeScript 支持，都是后续优化项，不能作为环境是否可用的判断依据。

先说说最基础的验证环节。很多人卡在“VSCode 调试失败”上，折腾半天代码格式，其实根子出在系统级环境没配好。关键不在 VSCode，而在系统终端能否全局识别 node 和 npm 命令。

第一步很容易验证：在系统终端（Windows 的 cmd/PowerShell，或者 macOS/Linux 的 Terminal）里分别执行 node -v 和 npm -v，两个都必须输出明确的版本号。Windows 上最常见的翻车原因，是安装时漏选了 Add to PATH 选项。如果已经装完了也没关系，手动把 C:\Program Files\nodejs（或你实际的安装路径）加进系统的 Path 变量，然后重启所有终端窗口就行。

macOS/Linux 如果用了 nvm 来管理 Node 版本，需要确认 source ~/.zshrc（或 ~/.bash_profile）已经写入，并且在新终端里执行过。用 which node 检查一下，返回的应该是 nvm 管理的路径，而不是 /usr/local/bin/node——如果指向后者，说明 nvm 的配置没生效。

还有一个容易忽略的细节：VSCode 内置终端可能缓存了旧的环境变量。解决办法很简单——关掉所有 VSCode 窗口，重新打开项目文件夹再试一次。

launch.json 中 program 字段别写死

接下来是调试配置。VSCode 自动生成的 launch.json 里，默认把 "program" 设成了 "${workspaceFolder}/app.js"。但实际项目的入口文件名五花八门，有叫 index.js 的，有叫 server.js 的，还有放在 src/ 目录下的。硬编码成 app.js，按 F5 启动调试时自然会报错。

这里有几个实用策略。如果只是跑单个文件调试，直接用 "program": "${file}"，F5 就会运行当前打开的 JS 文件，灵活性最高。如果项目有固定的入口文件，就明确设成 "program": "${workspaceFolder}/index.js"，但务必确保这个文件真实存在，而且里面有可执行的逻辑。

有一个容易被忽略的操作细节：调试之前一定要按 Ctrl+S（Windows/Linux）或 Cmd+S（macOS）保存文件——VSCode 不会自动保存未提交的修改。

如果项目是通过 npm start 来启动的，那就不需要改 program 字段了。正确的做法是设 "program": "npm"，再加上 "args": ["start"] 和 "console": "integratedTerminal"。否则启动日志都看不到，出了问题很难排查。

npm 全局工具和镜像要提前配好

npm -v 成功只是起点。后续装 nodemon、跑脚本的时候出错，往往是因为少配了两样东西。

国内开发者必须要换镜像：npm config set registry https://registry.npmmirror.com（这是当前可用的地址）。否则 npm install 那速度，真的能让人怀疑人生。

还有一个被很多人忽略的问题——C 盘空间。全局安装的工具多了，C 盘很快就不够用了。改一下全局路径就行。Windows 下可以执行 npm config set prefix "D:\npm-global"，然后再把这个路径加到系统 Path 里。验证是否生效也很简单：npm config get prefix 和 npm config get registry 必须输出你刚设的值。

设置完成后，重装一下全局工具，比如 npm install -g nodemon。之后在任意目录执行 nodemon index.js 应该能成功。如果 VSCode 终端里提示 command not found，说明终端没加载 shell 配置。要么重启 VSCode，要么手动执行 source ~/.zshrc，后者速度更快。

调试器依赖 npm 启动脚本，不是可选项

很多人以为 VSCode 的调试器是直接调用 node 二进制文件的。实际上，它底层依赖的是 npm 执行的启动流程。这意味着两件事：第一，如果 npm -v 失败，F5 必定报 Cannot find runtime 'node'——这和 launch.json 的写法无关，是环境本身没配好。

第二，如果想用 nodemon --inspect-brk 实现热重载调试，千万别把 nodemon 直接写进 program 字段。调试器不支持热替换，正确的做法是用 attach 模式：设置 "type": "node"、"request": "attach"、"port": 9229。

最后特别提醒一下 Windows 用户：安装 Node.js 时，路径里尽量不要出现中文或空格，否则 npm install 可能会静默失败——不报错，但模块实际上没装上。

说到底，整个配置过程中真正容易被忽略的，是 VSCode 终端是否继承了你 shell 里已经生效的 npm 配置。系统终端能用 nodemon，VSCode 里却不能，大概率是 shell 配置没加载，而不是 Node.js 没装好。搞清楚这一点，环境搭建这件事就没那么玄乎了。