写这篇指南的起因是我前段时间为了给两个项目分别维护 Node 16 和 Node 20 的运行环境在 Windows 上反复“卸载-安装-重配环境变量”折腾到怀疑人生。后来彻底切到 nvmNode Version Manager之后才意识到Windows 下做 Node.js 多版本管理并不是直接把 Mac/Linux 那套 nvm 搬过来就好很多细节和坑是 Windows 特有的。这篇指南就把我从安装、配置到日常使用全过程的经验写下来目标是让你能在 30 分钟内搭好一套稳定可用的 Windows nvm Node.js 环境。如果你正在为“装哪个版本的 Node.js”发愁又或者被家里老项目的 Node 版本卡住不敢升级这篇内容正好适合你。我会尽量把每一步背后的原因讲清楚这样你出问题时也能自己定位而不是只会复制命令。1. nvm 和 nvm-windows同一套名字下的两个完全不同的工具先说一个很多人都会搞混的点你在网上搜“Windows nvm”时出来的多数是 GitHub 上 coreybutler 维护的 nvm-windows而 Linux/macOS 上大家常用的 nvm 是 nvm-sh/nvm 这个项目。这两个项目同名但实现方式差别很大甚至连命令参数都有微妙出入。它们解决的是同一个痛点——在一台机器上安装多个 Node.js 版本随时切换——但理解的偏差会直接导致后续安装配置时踩坑。1.1 为什么 Windows 一直等不到官方版 nvmnvm 官方项目从出生起就是面向 Unix-like 系统的它大量使用 shell 脚本靠修改当前 shell 的 PATH 环境变量来切换 Node.js 版本。Windows 的 cmd、PowerShell 在环境变量处理和权限模型上与 Linux 完全不同所以 nvm-sh 官方一直不做 Windows 版本而是建议 Windows 用户去用社区方案。nvm-windows 就是这个社区方案里最主流的那个。提示不要试图在 Windows 上装 WSL 然后用 nvm-sh/nvm再做 Windows 侧调用。如果只是为管理 Node 版本nvm-windows 更直接侵入性更小。1.2 nvm-windows 的工作原理与 Mac/Linux 版的关键差异nvm-windows 的核心机制是“目录 符号链接 环境变量”。安装时它会在一个固定目录默认是C:\Users\你的用户名\AppData\Roaming\nvm下为每个已安装的 Node.js 版本建一个子目录比如v16.20.2、v20.11.0。当你执行nvm use 20.11.0时它会在C:\Program Files\nodejs这个位置NVM_SYMLINK 指向的路径创建一个符号链接链接到你刚指定的版本目录。之后你去任何终端敲node -vWindows 解析 PATH 时找到C:\Program Files\nodejs跟着符号链接就进到了具体的 Node 版本目录。这就是为什么安装 nvm-windows 之后系统 PATH 里永远只需要保留C:\Program Files\nodejs切换版本并不需要反复改环境变量。而 Mac/Linux 的原版 nvm 是在 shell 启动时动态修改 PATH 变量两者实现思路完全不同。这解释了一个常见疑问“为什么 nvm use 之后我已经打开的终端没反应必须重开一个”因为 nvm-windows 修改的是文件系统层面的符号链接理论上当前终端直接执行 node 命令就应该能生效但 Windows 对 PATH 的广播刷新往往不及时所以最稳妥的办法还是重开终端。搞清楚这个底层差异后面遇到“明明 nvm use 成功了node -v 还是旧版”这类问题你就不慌了。它大概率不是 nvm 坏了而是符号链接没生效或 PATH 优先级不对。2. 装 nvm-windows 之前先把这三个坑提前排掉安装一个工具本身不难难点在于旧环境没有清理干净。我在帮同事排查时发现大多数安装失败都和“历史上装过 Node.js”相关。所以这一节我把安装前的环境检查和安装过程写在一起照着做能避开 80% 的坑。2.1 卸载已有 Node.js血泪教训就在残留目录里如果电脑上已经装了 Node.js请先在“控制面板 - 程序和功能”里卸载干净。别跳过这步也别天真地以为“安装 nvm 时会自动接管旧版”。nvm-windows 的安装程序不会去处理已存在的 Node.js两个工具同时管理同一个C:\Program Files\nodejs目录轻则符号链接创建失败重则 PATH 里出现两条 Node 路径命令解析乱成一团。卸载之后手动检查以下目录是否还在有残留就直接删C:\Program Files\nodejsC:\Users\你的用户名\AppData\Roaming\npmC:\Users\你的用户名\AppData\Roaming\npm-cacheC:\Users\你的用户名\AppData\Local\Temp里和 node、npm 相关的临时文件如果你有全局安装过的脚手架工具建议先在旧环境里执行npm ls -g --depth0把清单导出来卸载后还能照着重装一遍。注意AppData\Roaming\npm这个目录很关键。npm 默认把全局安装的包放在这里卸载 Node 后这些包不会自动消失也不会被新环境自动识别。建议先备份或者记录清单不是直接删完拉倒。2.2 安装路径的“无空目录”硬性要求去 nvm-windows 的 GitHub releases 页面下载最新版我建议直接用nvm-setup.exe它会帮你配好环境变量省去手动折腾的麻烦。安装过程中有两个地方要特别留意安装路径不要出现空格和中文。默认是C:\Users\你的用户名\AppData\Roaming\nvm这个路径通常没问题。有些人想改到D:\Program Files\nvm空格会带来符号链接和命令行解析的潜在风险建议一律避免。指定的目录不能预先存在同名文件夹。如果C:\Program Files\nodejs还残留着安装程序可能报错或生成一个不完整的符号链接。这也是为什么第 2.1 节要先清理旧环境两件事是关联的。安装完成后打开一个新的 cmd 窗口输入nvm version如果能打印出版本号说明安装成功。如果提示“nvm 不是内部或外部命令”多半是环境变量没生效重开终端或者注销重登一次。2.3 settings.txt 里被忽略的两行配置nvm-windows 安装完成后会在安装目录生成一个settings.txt文件。这个文件通常长这样root: C:\Users\yuki\AppData\Roaming\nvm path: C:\Program Files\nodejs node_mirror: https://nodejs.org/dist/ npm_mirror: https://github.com/npm/cli/archive/很多人只盯着 root 和 path却忽略了node_mirror和npm_mirror这两行。它们决定了 nvm 从哪里下载 Node.js 发行版和 npm 压缩包。默认指向官方源网络条件差的时候下载会非常折磨人。提前把这两行改成国内镜像等会儿装版本能省出一大片时间。国内镜像地址无所谓唯一答案常年用下来 npmmirror 的源比较稳配置方式我放在第 3 节讲这里先把有这个字段记下来。2.4 权限与安全软件符号链接为什么会被静默拦截nvm use 时创建符号链接触及 Windows 的权限模型。系统默认要求“以管理员身份创建符号链接”所以执行nvm use的命令行窗口一定要用管理员权限打开。如果你用的是 Windows Terminal可以设置默认配置文件以管理员运行或者每次手动“以管理员身份运行”。有些安全软件会把“程序向系统目录创建符号链接”当作可疑行为直接拦截导致 nvm use 报错或者看似成功实际没生成链接。遇到安装和使用异常时先临时退出安全软件试一下。另外新版 nvm-windows 还支持在开发者模式下用非管理员权限创建符号链接但企业环境里组策略经常把这个开关禁用别把方案押在这条路上老老实实管理员权限最稳。3. 装完 nvm 不代表能直接拉版本镜像和环境变量这一步必须做很多人装完 nvm-windows兴冲冲执行nvm install 20.11.0然后卡在下载界面半天不动要么直接超时失败。这不是 nvm 坏是下载源网络太烂。镜像配置这一节我建议你在安装任何 Node 版本之前就先配好。3.1 给 nvm 配国内镜像下载速度从龟速到秒开编辑 nvm 安装目录下的settings.txt把两行改成node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/改完保存后重新运行nvm install 20.11.0你会明显感觉到下载速度提升。原因很简单npmmirror 在国内有大量镜像节点拉取 Node.js 官方发行版的 zip 包几乎能跑满带宽而直连 nodejs.org 经常受国际网络波动影响。这里提醒一句node_mirror是给 nvm 下载 Node.js 运行时用的npm_mirror是给 nvm 下载 npm 压缩包用的。两者分开配置缺一不可。有些教程只改了node_mirror装完 Node 后 npm 版本文件下载失败查半天才发现第二个字段没配。3.2 npm registry 需要单独配置别只盯着 nvmnvm 的镜像配置只解决“下载 Node.js 本身”和“下载 npm 压缩包”两个问题。你后续用npm install安装各种包时npm 访问的是另一个地址也就是 npm registry它默认指向https://registry.npmjs.org/。这个地址在国内同样不稳定需要在每个 Node 版本里单独配置。执行以下命令npm config set registry https://registry.npmmirror.com/建议顺手验证一下npm config get registry输出应为https://registry.npmmirror.com/。这里有个容易忽略的点nvm-windows 切换 Node 版本后每个版本的 Node 自带一套 npm 配置但用户级配置存在用户目录.npmrc里的那部分是共享的。所以在当前版本设置 registry其他版本也会继承同一份用户级配置不用每个版本都去执行一遍。我早期不懂这个每切一个版本就重新设一次 registry后来才发现纯属重复劳动。3.3 NVM_HOME 与 NVM_SYMLINK环境变量到底该怎么设如果你用的是nvm-setup.exe安装环境变量通常是自动挂上的不需要手动改。但我经常遇到有人因为某些教程手动配环境变量时激进的把整条 PATH 改坏。这里把原理讲清楚方便你自查。nvm-windows 涉及两个关键环境变量变量名指向路径作用NVM_HOMEnvm 安装目录如C:\Users\yuki\AppData\Roaming\nvmnvm 程序自己读取该目录下的 settings.txt保存已安装的各版本 NodeNVM_SYMLINKC:\Program Files\nodejsnvm 生成的符号链接目录也必须是 PATH 中实际生效的 Node 入口安装程序通常只会在 PATH 中写入%NVM_HOME%和%NVM_SYMLINK%两个条目顺序通常是%NVM_SYMLINK%在前。这个顺序最好保持因为如果系统里还有其他 Node 路径写入了 PATH且排在这个符号链接前面node命令就会命中错误的目标。手动检查系统环境变量时注意不要画蛇添足去加C:\Program Files\nodejs\v20.11.0这类具体版本路径。一旦你这么做了nvm 的符号链接机制就形同虚设切换到其他版本时这条硬编码路径仍然生效永远都在调旧版本。这也是最常见的一种“切换失效”原因。4. 日常管理 Node 版本从安装、切换到全局模块的心智模型环境配好之后日常操作其实就集中在几个命令上。我先把命令清单列出来再讲两个必须理解的原理性问题切换版本后全局模块去哪了以及为什么 IDE 内切版本经常会翻车。4.1 高频命令清单与一次完整切换实战以下命令都在管理员权限的 cmd 或 PowerShell 中执行# 查看当前 nvm 版本 nvm version # 列出远端所有可安装的 Node.js 版本部分镜像源下可能不完整 nvm list available # 安装指定长期维护版 nvm install 20.11.0 # 安装某个大版本的最新版 nvm install 20 # 安装 Node.js 官方最新发布版 nvm install latest # 查看本机已安装的版本带 * 号的是当前正在使用的版本 nvm list # 切换到指定版本 nvm use 20.11.0 # 卸载指定版本 nvm uninstall 16.20.2 # 给某个版本设置别名 nvm alias default 20.11.0 # 查看当前正在使用的版本 nvm current实际操作一次假设我想在 Node 16 和 Node 20 间来回切换nvm install 16.20.2 nvm install 20.11.0 nvm use 16.20.2 node -v # v16.20.2 nvm use 20.11.0 node -v # v20.11.0注意这里的nvm alias default 20.11.0。如果你不设置默认别名新开的终端不会自动进入任何版本必须手动nvm use一次否则node命令会直接提示找不到。设置默认别名之后新终端打开即可直接使用默认版本这是提升日常体验很重要的一步很多教程都只是简单带过。4.2 版本切换后全局安装的包到底还在不在这个问题经常有人问因为它关系到你在 20 版本下npm install -g装的东西切到 16 版本还能不能用。nvm-windows 的机制是这样的npm 全局包的安装位置默认在用户目录的AppData\Roaming\npm这个目录的优先级高于 nvm 管理的 Node 版本目录。也就是说多个 Node 版本共享同一个全局模块目录。这意味着你在 20 版本下npm install -g yarn切到 16 版本后yarn -v大概率仍然能用前提是 yarn 的 Node 引擎要求兼容 16。这个“共享”看起来方便但也带来两个隐性风险某些包通过npm install -g安装了带有原生模块的二进制文件这些二进制文件针对特定 Node ABIApplication Binary Interface应用二进制接口编译。切换 Node 版本后可能 ABI 不兼容表现为启动报错或直接黑窗口闪退。如果你在不同项目间频繁切换 Node 版本依赖某个全局包时它对应的版本可能并不适合当前 Node。项目局部依赖永远比全局依赖更可控全局只建议安装yarn、pnpm、nodemon、ts-node这类跨版本稳定的基础工具。想验证当前全局模块的安装位置可以执行npm config get prefix输出通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个值被某些教程改成了其他目录那就要小心了因为 nvm 切换版本后全局工具链可能会彻底失效。4.3 use 的权限问题与 IDE 内切换失败的真正原因nvm use 需要管理员权限这在第 2.4 节已经提过。这里再深入讲一下它在实际开发环境中的连锁反应。VS Code、WebStorm 这些 IDE 内置的终端默认继承的是 GUI 进程的权限。如果你不是以管理员身份启动 IDE那么 IDE 内置终端里的nvm use大概率会失败报错类似“无法创建符号链接客户端没有所需的特权”。哪怕你改动了系统里的某个开关VSCode 也未必会立即感知。所以我的日常习惯是在独立的管理员 CMD 窗口执行nvm use切换版本。切完再打开普通 IDE 窗口进行开发。如果必须在 IDE 内切换就把 IDE 整个以管理员身份启动再在内部终端操作。这种工作方式看起来多一步实际上省去了很多“明明切换成功但 IDE 里 node -v 还是旧版本”的困惑时间。同理Git Bash、PowerShell、cmd 之间互不影响只要它们解析的是同一个C:\Program Files\nodejs符号链接版本就是一致的。5. 高频报错的定位链路从提示信息反查根因我这几年见过太多人在安装 nvm 时被各种报错劝退其实多数报错背后就那几类原因。下面按错误现象做一次系统梳理每个问题都给排查路径和解决方案。5.1 “node 不是内部或外部命令”——先问自己三个问题这个报错出现在两种情况一是刚装完 nvm 还从未执行过nvm use二是环境变量被改乱。挨个排查是否已经执行过nvm use 版本号没有就先执行一次然后重开终端。nvm list能不能正常列出已安装版本如果 nvm 本身能用而 node 不行多半是 NVM_SYMLINK 指向的目录压根不存在检查C:\Program Files\nodejs是否存在。系统 PATH 中是否包含%NVM_HOME%和%NVM_SYMLINK%两个都必须在且建议%NVM_SYMLINK%排在前面。值得注意的是nvm use成功并不代表符号链接一定创建成功。执行完可以用文件资源管理器到C:\Program Files下看有没有nodejs这个目录或者直接在管理员 CMD 里执行dir C:\Program Files\nodejs如果目录存在但内容为空说明符号链接创建失败常见是权限或杀软拦截。5.2 “is not yet released”——版本号写错还是镜像同步延迟这个报错的典型形态是error installing 24.20.0: node.js v24.20.0 is not yet released or is not available很多人看到“is not yet released”会以为 Node 官方还没发布这个版本但更多情况是版本号本身就不存在或者你用的镜像源还没同步到这个版本。排查步骤执行nvm list available看列表里有没有你要的版本。如果列表里没有但官方 GitHub releases 里有说明你的node_mirror镜像同步慢等一阵或者临时把node_mirror改回官方源下载一次。确认版本号格式。nvm 安装的版本号必须与官方发布的版本号一致比如24.20.0这种格式不要删掉前导 v 也别自己脑补版本号。大多数情况下改成实际存在的版本号即可解决。这类问题常见于“看网上文章说某个版本好随手照着敲”的情况。记住先nvm list available查实际可用的版本再决定装什么。5.3 切换到旧版本后 npm 异常——版本兼容性要自己想清楚如果你的某个项目要求 Node 14但你的 npm 全局包都是用 Node 20 安装的切到 Node 14 后npm -v可能正常但npm install可能报各种奇怪错误。原因在于项目里的node_modules、lockfile 版本和 Node 版本不完全匹配。顺带说一个很隐蔽的坑如果你执行过npm install -g npm最新版新版本 npm 需要的 Node 版本可能超过你切到的旧版本。例如 Node 14 默认装 npm 6但你把全局 npm 强制升到了 9切回 Node 14 后 npm 直接拒绝运行。排查时用npm -v看版本如果发现全局 npm 版本过高在当前 Node 版本下重装匹配的 npmnpm install -g npm对应版本总之不要在全局环境里长期维护一堆依赖特定 Node ABI 的工具。项目内用 package.json 锁定全局保持精简是降低这一类故障的最好方法。5.4 未雨绸缪重装时如何彻底清理 nvm-windows最后聊一下重装。nvm-windows 卸载不彻底会导致重装后各种灵异现象我自己的做法是这样先记录当前所有 Node 版本nvm list。执行 nvm 自带的卸载程序或从控制面板卸载。手动删除C:\Program Files\nodejs目录如果有残留符号链接或文件。删除 nvm 安装目录下的所有版本目录定位到%NVM_HOME%把里面v*开头的目录全部删掉。打开系统环境变量编辑器移除NVM_HOME、NVM_SYMLINK并检查 PATH 中残留的C:\Program Files\nodejs条目。清理AppData\Roaming\npm和AppData\Roaming\npm-cache如果确定不用保留全局包的话。清理干净后再重新安装 nvm-windows环境就会像第一次安装一样干净。不这么做的话残留的符号链接会让新 nvm 生成的链接指向错误目录最终表现就是“安装成功但 node 命令找不到”。根据自己的实际体验Windows 下用 nvm 管理 Node.js 最大的价值不是“装多个版本”而是“在多个项目之间瞬间切换而不用重装系统级环境”。用熟了之后你会发现自己再也没有手动改过 PATH再也没有因为某个老项目而不敢升级 Node.js。建议你把镜像配置、默认别名、管理员权限这几个点一次性配到位后面真的就是一条nvm install、nvm use的事。
写这篇指南的起因是我前段时间为了给两个项目分别维护 Node 16 和 Node 20 的运行环境在 Windows 上反复“卸载-安装-重配环境变量”折腾到怀疑人生。后来彻底切到 nvmNode Version Manager之后才意识到Windows 下做 Node.js 多版本管理并不是直接把 Mac/Linux 那套 nvm 搬过来就好很多细节和坑是 Windows 特有的。这篇指南就把我从安装、配置到日常使用全过程的经验写下来目标是让你能在 30 分钟内搭好一套稳定可用的 Windows nvm Node.js 环境。如果你正在为“装哪个版本的 Node.js”发愁又或者被家里老项目的 Node 版本卡住不敢升级这篇内容正好适合你。我会尽量把每一步背后的原因讲清楚这样你出问题时也能自己定位而不是只会复制命令。1. nvm 和 nvm-windows同一套名字下的两个完全不同的工具先说一个很多人都会搞混的点你在网上搜“Windows nvm”时出来的多数是 GitHub 上 coreybutler 维护的 nvm-windows而 Linux/macOS 上大家常用的 nvm 是 nvm-sh/nvm 这个项目。这两个项目同名但实现方式差别很大甚至连命令参数都有微妙出入。它们解决的是同一个痛点——在一台机器上安装多个 Node.js 版本随时切换——但理解的偏差会直接导致后续安装配置时踩坑。1.1 为什么 Windows 一直等不到官方版 nvmnvm 官方项目从出生起就是面向 Unix-like 系统的它大量使用 shell 脚本靠修改当前 shell 的 PATH 环境变量来切换 Node.js 版本。Windows 的 cmd、PowerShell 在环境变量处理和权限模型上与 Linux 完全不同所以 nvm-sh 官方一直不做 Windows 版本而是建议 Windows 用户去用社区方案。nvm-windows 就是这个社区方案里最主流的那个。提示不要试图在 Windows 上装 WSL 然后用 nvm-sh/nvm再做 Windows 侧调用。如果只是为管理 Node 版本nvm-windows 更直接侵入性更小。1.2 nvm-windows 的工作原理与 Mac/Linux 版的关键差异nvm-windows 的核心机制是“目录 符号链接 环境变量”。安装时它会在一个固定目录默认是C:\Users\你的用户名\AppData\Roaming\nvm下为每个已安装的 Node.js 版本建一个子目录比如v16.20.2、v20.11.0。当你执行nvm use 20.11.0时它会在C:\Program Files\nodejs这个位置NVM_SYMLINK 指向的路径创建一个符号链接链接到你刚指定的版本目录。之后你去任何终端敲node -vWindows 解析 PATH 时找到C:\Program Files\nodejs跟着符号链接就进到了具体的 Node 版本目录。这就是为什么安装 nvm-windows 之后系统 PATH 里永远只需要保留C:\Program Files\nodejs切换版本并不需要反复改环境变量。而 Mac/Linux 的原版 nvm 是在 shell 启动时动态修改 PATH 变量两者实现思路完全不同。这解释了一个常见疑问“为什么 nvm use 之后我已经打开的终端没反应必须重开一个”因为 nvm-windows 修改的是文件系统层面的符号链接理论上当前终端直接执行 node 命令就应该能生效但 Windows 对 PATH 的广播刷新往往不及时所以最稳妥的办法还是重开终端。搞清楚这个底层差异后面遇到“明明 nvm use 成功了node -v 还是旧版”这类问题你就不慌了。它大概率不是 nvm 坏了而是符号链接没生效或 PATH 优先级不对。2. 装 nvm-windows 之前先把这三个坑提前排掉安装一个工具本身不难难点在于旧环境没有清理干净。我在帮同事排查时发现大多数安装失败都和“历史上装过 Node.js”相关。所以这一节我把安装前的环境检查和安装过程写在一起照着做能避开 80% 的坑。2.1 卸载已有 Node.js血泪教训就在残留目录里如果电脑上已经装了 Node.js请先在“控制面板 - 程序和功能”里卸载干净。别跳过这步也别天真地以为“安装 nvm 时会自动接管旧版”。nvm-windows 的安装程序不会去处理已存在的 Node.js两个工具同时管理同一个C:\Program Files\nodejs目录轻则符号链接创建失败重则 PATH 里出现两条 Node 路径命令解析乱成一团。卸载之后手动检查以下目录是否还在有残留就直接删C:\Program Files\nodejsC:\Users\你的用户名\AppData\Roaming\npmC:\Users\你的用户名\AppData\Roaming\npm-cacheC:\Users\你的用户名\AppData\Local\Temp里和 node、npm 相关的临时文件如果你有全局安装过的脚手架工具建议先在旧环境里执行npm ls -g --depth0把清单导出来卸载后还能照着重装一遍。注意AppData\Roaming\npm这个目录很关键。npm 默认把全局安装的包放在这里卸载 Node 后这些包不会自动消失也不会被新环境自动识别。建议先备份或者记录清单不是直接删完拉倒。2.2 安装路径的“无空目录”硬性要求去 nvm-windows 的 GitHub releases 页面下载最新版我建议直接用nvm-setup.exe它会帮你配好环境变量省去手动折腾的麻烦。安装过程中有两个地方要特别留意安装路径不要出现空格和中文。默认是C:\Users\你的用户名\AppData\Roaming\nvm这个路径通常没问题。有些人想改到D:\Program Files\nvm空格会带来符号链接和命令行解析的潜在风险建议一律避免。指定的目录不能预先存在同名文件夹。如果C:\Program Files\nodejs还残留着安装程序可能报错或生成一个不完整的符号链接。这也是为什么第 2.1 节要先清理旧环境两件事是关联的。安装完成后打开一个新的 cmd 窗口输入nvm version如果能打印出版本号说明安装成功。如果提示“nvm 不是内部或外部命令”多半是环境变量没生效重开终端或者注销重登一次。2.3 settings.txt 里被忽略的两行配置nvm-windows 安装完成后会在安装目录生成一个settings.txt文件。这个文件通常长这样root: C:\Users\yuki\AppData\Roaming\nvm path: C:\Program Files\nodejs node_mirror: https://nodejs.org/dist/ npm_mirror: https://github.com/npm/cli/archive/很多人只盯着 root 和 path却忽略了node_mirror和npm_mirror这两行。它们决定了 nvm 从哪里下载 Node.js 发行版和 npm 压缩包。默认指向官方源网络条件差的时候下载会非常折磨人。提前把这两行改成国内镜像等会儿装版本能省出一大片时间。国内镜像地址无所谓唯一答案常年用下来 npmmirror 的源比较稳配置方式我放在第 3 节讲这里先把有这个字段记下来。2.4 权限与安全软件符号链接为什么会被静默拦截nvm use 时创建符号链接触及 Windows 的权限模型。系统默认要求“以管理员身份创建符号链接”所以执行nvm use的命令行窗口一定要用管理员权限打开。如果你用的是 Windows Terminal可以设置默认配置文件以管理员运行或者每次手动“以管理员身份运行”。有些安全软件会把“程序向系统目录创建符号链接”当作可疑行为直接拦截导致 nvm use 报错或者看似成功实际没生成链接。遇到安装和使用异常时先临时退出安全软件试一下。另外新版 nvm-windows 还支持在开发者模式下用非管理员权限创建符号链接但企业环境里组策略经常把这个开关禁用别把方案押在这条路上老老实实管理员权限最稳。3. 装完 nvm 不代表能直接拉版本镜像和环境变量这一步必须做很多人装完 nvm-windows兴冲冲执行nvm install 20.11.0然后卡在下载界面半天不动要么直接超时失败。这不是 nvm 坏是下载源网络太烂。镜像配置这一节我建议你在安装任何 Node 版本之前就先配好。3.1 给 nvm 配国内镜像下载速度从龟速到秒开编辑 nvm 安装目录下的settings.txt把两行改成node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/改完保存后重新运行nvm install 20.11.0你会明显感觉到下载速度提升。原因很简单npmmirror 在国内有大量镜像节点拉取 Node.js 官方发行版的 zip 包几乎能跑满带宽而直连 nodejs.org 经常受国际网络波动影响。这里提醒一句node_mirror是给 nvm 下载 Node.js 运行时用的npm_mirror是给 nvm 下载 npm 压缩包用的。两者分开配置缺一不可。有些教程只改了node_mirror装完 Node 后 npm 版本文件下载失败查半天才发现第二个字段没配。3.2 npm registry 需要单独配置别只盯着 nvmnvm 的镜像配置只解决“下载 Node.js 本身”和“下载 npm 压缩包”两个问题。你后续用npm install安装各种包时npm 访问的是另一个地址也就是 npm registry它默认指向https://registry.npmjs.org/。这个地址在国内同样不稳定需要在每个 Node 版本里单独配置。执行以下命令npm config set registry https://registry.npmmirror.com/建议顺手验证一下npm config get registry输出应为https://registry.npmmirror.com/。这里有个容易忽略的点nvm-windows 切换 Node 版本后每个版本的 Node 自带一套 npm 配置但用户级配置存在用户目录.npmrc里的那部分是共享的。所以在当前版本设置 registry其他版本也会继承同一份用户级配置不用每个版本都去执行一遍。我早期不懂这个每切一个版本就重新设一次 registry后来才发现纯属重复劳动。3.3 NVM_HOME 与 NVM_SYMLINK环境变量到底该怎么设如果你用的是nvm-setup.exe安装环境变量通常是自动挂上的不需要手动改。但我经常遇到有人因为某些教程手动配环境变量时激进的把整条 PATH 改坏。这里把原理讲清楚方便你自查。nvm-windows 涉及两个关键环境变量变量名指向路径作用NVM_HOMEnvm 安装目录如C:\Users\yuki\AppData\Roaming\nvmnvm 程序自己读取该目录下的 settings.txt保存已安装的各版本 NodeNVM_SYMLINKC:\Program Files\nodejsnvm 生成的符号链接目录也必须是 PATH 中实际生效的 Node 入口安装程序通常只会在 PATH 中写入%NVM_HOME%和%NVM_SYMLINK%两个条目顺序通常是%NVM_SYMLINK%在前。这个顺序最好保持因为如果系统里还有其他 Node 路径写入了 PATH且排在这个符号链接前面node命令就会命中错误的目标。手动检查系统环境变量时注意不要画蛇添足去加C:\Program Files\nodejs\v20.11.0这类具体版本路径。一旦你这么做了nvm 的符号链接机制就形同虚设切换到其他版本时这条硬编码路径仍然生效永远都在调旧版本。这也是最常见的一种“切换失效”原因。4. 日常管理 Node 版本从安装、切换到全局模块的心智模型环境配好之后日常操作其实就集中在几个命令上。我先把命令清单列出来再讲两个必须理解的原理性问题切换版本后全局模块去哪了以及为什么 IDE 内切版本经常会翻车。4.1 高频命令清单与一次完整切换实战以下命令都在管理员权限的 cmd 或 PowerShell 中执行# 查看当前 nvm 版本 nvm version # 列出远端所有可安装的 Node.js 版本部分镜像源下可能不完整 nvm list available # 安装指定长期维护版 nvm install 20.11.0 # 安装某个大版本的最新版 nvm install 20 # 安装 Node.js 官方最新发布版 nvm install latest # 查看本机已安装的版本带 * 号的是当前正在使用的版本 nvm list # 切换到指定版本 nvm use 20.11.0 # 卸载指定版本 nvm uninstall 16.20.2 # 给某个版本设置别名 nvm alias default 20.11.0 # 查看当前正在使用的版本 nvm current实际操作一次假设我想在 Node 16 和 Node 20 间来回切换nvm install 16.20.2 nvm install 20.11.0 nvm use 16.20.2 node -v # v16.20.2 nvm use 20.11.0 node -v # v20.11.0注意这里的nvm alias default 20.11.0。如果你不设置默认别名新开的终端不会自动进入任何版本必须手动nvm use一次否则node命令会直接提示找不到。设置默认别名之后新终端打开即可直接使用默认版本这是提升日常体验很重要的一步很多教程都只是简单带过。4.2 版本切换后全局安装的包到底还在不在这个问题经常有人问因为它关系到你在 20 版本下npm install -g装的东西切到 16 版本还能不能用。nvm-windows 的机制是这样的npm 全局包的安装位置默认在用户目录的AppData\Roaming\npm这个目录的优先级高于 nvm 管理的 Node 版本目录。也就是说多个 Node 版本共享同一个全局模块目录。这意味着你在 20 版本下npm install -g yarn切到 16 版本后yarn -v大概率仍然能用前提是 yarn 的 Node 引擎要求兼容 16。这个“共享”看起来方便但也带来两个隐性风险某些包通过npm install -g安装了带有原生模块的二进制文件这些二进制文件针对特定 Node ABIApplication Binary Interface应用二进制接口编译。切换 Node 版本后可能 ABI 不兼容表现为启动报错或直接黑窗口闪退。如果你在不同项目间频繁切换 Node 版本依赖某个全局包时它对应的版本可能并不适合当前 Node。项目局部依赖永远比全局依赖更可控全局只建议安装yarn、pnpm、nodemon、ts-node这类跨版本稳定的基础工具。想验证当前全局模块的安装位置可以执行npm config get prefix输出通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个值被某些教程改成了其他目录那就要小心了因为 nvm 切换版本后全局工具链可能会彻底失效。4.3 use 的权限问题与 IDE 内切换失败的真正原因nvm use 需要管理员权限这在第 2.4 节已经提过。这里再深入讲一下它在实际开发环境中的连锁反应。VS Code、WebStorm 这些 IDE 内置的终端默认继承的是 GUI 进程的权限。如果你不是以管理员身份启动 IDE那么 IDE 内置终端里的nvm use大概率会失败报错类似“无法创建符号链接客户端没有所需的特权”。哪怕你改动了系统里的某个开关VSCode 也未必会立即感知。所以我的日常习惯是在独立的管理员 CMD 窗口执行nvm use切换版本。切完再打开普通 IDE 窗口进行开发。如果必须在 IDE 内切换就把 IDE 整个以管理员身份启动再在内部终端操作。这种工作方式看起来多一步实际上省去了很多“明明切换成功但 IDE 里 node -v 还是旧版本”的困惑时间。同理Git Bash、PowerShell、cmd 之间互不影响只要它们解析的是同一个C:\Program Files\nodejs符号链接版本就是一致的。5. 高频报错的定位链路从提示信息反查根因我这几年见过太多人在安装 nvm 时被各种报错劝退其实多数报错背后就那几类原因。下面按错误现象做一次系统梳理每个问题都给排查路径和解决方案。5.1 “node 不是内部或外部命令”——先问自己三个问题这个报错出现在两种情况一是刚装完 nvm 还从未执行过nvm use二是环境变量被改乱。挨个排查是否已经执行过nvm use 版本号没有就先执行一次然后重开终端。nvm list能不能正常列出已安装版本如果 nvm 本身能用而 node 不行多半是 NVM_SYMLINK 指向的目录压根不存在检查C:\Program Files\nodejs是否存在。系统 PATH 中是否包含%NVM_HOME%和%NVM_SYMLINK%两个都必须在且建议%NVM_SYMLINK%排在前面。值得注意的是nvm use成功并不代表符号链接一定创建成功。执行完可以用文件资源管理器到C:\Program Files下看有没有nodejs这个目录或者直接在管理员 CMD 里执行dir C:\Program Files\nodejs如果目录存在但内容为空说明符号链接创建失败常见是权限或杀软拦截。5.2 “is not yet released”——版本号写错还是镜像同步延迟这个报错的典型形态是error installing 24.20.0: node.js v24.20.0 is not yet released or is not available很多人看到“is not yet released”会以为 Node 官方还没发布这个版本但更多情况是版本号本身就不存在或者你用的镜像源还没同步到这个版本。排查步骤执行nvm list available看列表里有没有你要的版本。如果列表里没有但官方 GitHub releases 里有说明你的node_mirror镜像同步慢等一阵或者临时把node_mirror改回官方源下载一次。确认版本号格式。nvm 安装的版本号必须与官方发布的版本号一致比如24.20.0这种格式不要删掉前导 v 也别自己脑补版本号。大多数情况下改成实际存在的版本号即可解决。这类问题常见于“看网上文章说某个版本好随手照着敲”的情况。记住先nvm list available查实际可用的版本再决定装什么。5.3 切换到旧版本后 npm 异常——版本兼容性要自己想清楚如果你的某个项目要求 Node 14但你的 npm 全局包都是用 Node 20 安装的切到 Node 14 后npm -v可能正常但npm install可能报各种奇怪错误。原因在于项目里的node_modules、lockfile 版本和 Node 版本不完全匹配。顺带说一个很隐蔽的坑如果你执行过npm install -g npm最新版新版本 npm 需要的 Node 版本可能超过你切到的旧版本。例如 Node 14 默认装 npm 6但你把全局 npm 强制升到了 9切回 Node 14 后 npm 直接拒绝运行。排查时用npm -v看版本如果发现全局 npm 版本过高在当前 Node 版本下重装匹配的 npmnpm install -g npm对应版本总之不要在全局环境里长期维护一堆依赖特定 Node ABI 的工具。项目内用 package.json 锁定全局保持精简是降低这一类故障的最好方法。5.4 未雨绸缪重装时如何彻底清理 nvm-windows最后聊一下重装。nvm-windows 卸载不彻底会导致重装后各种灵异现象我自己的做法是这样先记录当前所有 Node 版本nvm list。执行 nvm 自带的卸载程序或从控制面板卸载。手动删除C:\Program Files\nodejs目录如果有残留符号链接或文件。删除 nvm 安装目录下的所有版本目录定位到%NVM_HOME%把里面v*开头的目录全部删掉。打开系统环境变量编辑器移除NVM_HOME、NVM_SYMLINK并检查 PATH 中残留的C:\Program Files\nodejs条目。清理AppData\Roaming\npm和AppData\Roaming\npm-cache如果确定不用保留全局包的话。清理干净后再重新安装 nvm-windows环境就会像第一次安装一样干净。不这么做的话残留的符号链接会让新 nvm 生成的链接指向错误目录最终表现就是“安装成功但 node 命令找不到”。根据自己的实际体验Windows 下用 nvm 管理 Node.js 最大的价值不是“装多个版本”而是“在多个项目之间瞬间切换而不用重装系统级环境”。用熟了之后你会发现自己再也没有手动改过 PATH再也没有因为某个老项目而不敢升级 Node.js。建议你把镜像配置、默认别名、管理员权限这几个点一次性配到位后面真的就是一条nvm install、nvm use的事。
