nvm-windows 管理 Node.js 多版本与切换报错排查

脚本专家

为什么 Windows 上要用 nvm-windows 管理 Node.js

实际开发中经常出现版本分裂：一个老项目锁定 Node 16，另一个新项目要求 Node 20。手动卸载再重装既费时又容易把全局包和 PATH 搞坏。nvm（Node Version Manager）的作用就是把多个 Node.js 版本并行装在本地，通过切换符号链接让 node 与 npm 指向选中的版本。

需要提前明确一点：官方 nvm 只支持 macOS 与 Linux，Windows 上使用的是社区维护的 nvm-windows（作者 coreybutler），两者命令风格接近但并非同一套实现，例如 nvm-windows 不原生读取 .nvmrc。下面的流程基于 Windows 10/11 与 nvm-windows 1.1.x 实测路径整理。

一、先彻底卸载已有的 Node.js

nvm-windows 要求系统里不能存在独立安装的 Node.js，否则符号链接会与原有安装冲突，表现为 nvm use 成功但 node -v 仍是旧版本。清理分三步：

1) 控制面板 → 程序和功能，找到 Node.js 右键卸载；
2) 删除残留目录，常见为 C:\Program Files\nodejs 与 C:\Users\<用户名>\AppData\Local\npm；
3) 清理环境变量：Win + R 输入 sysdm.cpl → 高级 → 环境变量，在系统变量和用户变量的 Path 中删除所有包含 nodejs、npm 的条目。

完成后重开命令提示符，执行 node -v 应提示“不是内部或外部命令”，这说明旧环境已清干净。若此时仍能输出版本号，说明 PATH 里还残留着别的 Node 路径，需要继续排查。

二、安装 nvm-windows

安装包从 GitHub 仓库 releases 页获取（https://github.com/coreybutler/nvm-windows/releases）。推荐下载 nvm-setup.exe 图形化安装程序；nvm-noinstall.zip 是免安装版，需要手动配置环境变量，只适合熟悉机制的场景。

安装向导中有两个路径必须留意：

- nvm 安装路径：存放 nvm 本体和所有已下载的 Node 版本，默认类似 C:\Users\admin\AppData\Local\nvm；
- Node.js 符号链接路径：默认 C:\Program Files\nodejs，这个目录是 node 命令的入口，路径中不能含空格和中文，否则切换版本时容易失败。

安装程序会自动写入环境变量。装完后以管理员身份打开 CMD 或 PowerShell，因为创建符号链接需要相应权限：

2. nvm version

复制代码

能输出类似 1.1.12 的版本号即安装成功。如果提示“不是内部或外部命令”，依次检查：旧 Node 是否卸载干净、终端是否重启、PATH 中是否包含 nvm 目录。

三、安装与切换 Node.js 版本

先用 list available 看远端可安装列表（含 LTS 与 Current 标记），再按需安装：

2. nvm list available
3. nvm install 20.12.0
4. nvm install 18
5. nvm list

复制代码

nvm install 后面给完整版本号表示精确安装；只给主版本号（如 18）时，会自动补全该系列的最新子版本；nvm install lts 安装最新长期支持版，nvm install latest 安装最新开发版。安装过程会把对应版本解压到 nvm root 目录下的版本文件夹中。

切换并验证：

2. nvm use 20.12.0
3. node -v
4. npm -v

复制代码

切换成功后，node 与 npm 会立即指向所选版本。npm 是随 Node 一起分发的，每个版本都有独立的 npm，因此不要手动去改 PATH 里的 npm 路径，否则会出现切换版本后 npm 命令失效的问题。

四、常用命令与默认版本

信息类：nvm version（或 -v）查看自身版本，nvm help 查看全部命令，nvm root 显示版本存放根目录（示例输出 C:\Users\Alice\AppData\Roaming\nvm），nvm current 显示当前生效版本。

查看与切换：nvm list 或 nvm ls 列出本地已装版本并用星号标记当前版本；nvm list available 列出远端可安装版本；nvm use <version> 精确切换，nvm use <major> 切换到该主版本已安装的最新子版本。

卸载：nvm uninstall <version> 需给出完整版本号，且不能卸载正在使用的版本，必须先 nvm use 切到别的版本再卸载，例如：

2. nvm use 20.12.0
3. nvm uninstall 16.14.0

复制代码

设置默认版本，让新开的终端自动生效：

2. nvm alias default 20.12.0
3. nvm alias

复制代码

nvm alias 会列出所有别名，输出形如 default -> 20.12.0。日常把主力版本设为 LTS（18、20、22）比较稳妥。

五、用 settings.txt 配置国内镜像加速

nvm 默认从 nodejs.org 拉取，国内下载慢或失败是高频问题。解决办法是修改 nvm 安装目录下的 settings.txt（不存在则新建），加入两行：

2. node_mirror: https://npmmirror.com/mirrors/node/
3. npm_mirror: https://npmmirror.com/mirrors/npm/

复制代码

保存后重新执行 nvm install，包会从 npmmirror.com 下载，速度明显提升。需要注意的是镜像配置写在设置文件里，而不是靠命令行参数传入。

六、.nvmrc 在 Windows 上的变通处理

项目根目录若有 .nvmrc（内容形如 18.17.0），在 macOS/Linux 上直接 nvm use 即可。nvm-windows 不原生支持自动读取，可先取值再切换：

CMD 下：

2. for /f %i in (.nvmrc) do nvm use %i

复制代码

PowerShell 下：

2. nvm use (Get-Content .nvmrc)

复制代码

另外可用 node -p "process.arch" 确认当前是 x64 版本，nvm-windows 默认安装 64 位包。

七、三个典型故障的排查思路

1) nvm use 报 “exit status 1: Access is denied.”：本质是权限不足，无法创建或改写符号链接。以管理员身份运行终端，或确认 C:\Program Files\nodejs 目录对当前用户可写。

2) 切换版本后 npm 命令失效：多因 PATH 中存在手工添加的 npm 路径，或切换动作没真正生效。先用 nvm current 与 nvm list 确认当前版本，再检查 PATH 只保留 nvm 管理的入口，不要额外指向某个具体版本的 npm。

3) 下载慢或失败：按上一节写入 node_mirror 与 npm_mirror 后重试；若某个版本的缓存已损坏，可进入 nvm root 对应版本目录手动删除后重新安装。npm 缓存也可用 npm cache clean --force 清理，但要注意每个 Node 版本有独立缓存。

八、维护与最佳实践

定期清理不用的旧版本可直接在 nvm root 目录删除对应文件夹，或在非当前版本上使用 nvm uninstall。保留两到三个常用版本（如 18、20、22）即可覆盖多数项目，配合 nvm alias default 固定主力版本，团队协作时把 .nvmrc 一并提交到仓库，减少“我这能跑你那不能跑”的环境差异。遇到 node 命令整体失效的极端情况，优先检查 C:\Program Files\nodejs 是否仍是 nvm 创建的符号链接，以及它是否还在系统 PATH 中。

热心网友7

感谢楼主写这么细，nvm-windows 和官方 nvm 不是一套实现这一点确实要先说清楚，我当初就是照着 macOS 的教程敲 nvm use，结果压根不读 .nvmrc，白折腾半天，后来才改用 for /f 那行命令。 几个自己踩过的坑补充一下： 一是卸载旧 Node 那步千万别偷懒，我有一次只卸了程序没清 Path，nvm use 显示成功但 node -v 还是老版本，查了快一小时才发现系统变量里还留着一条。 二是安装路径，楼主说符号链接目录别带空格和中文，我更进一步，直接把 nvm 根目录也挪到了 C:\nvm，链接目录用 C:\nodejs。因为默认的根目录在用户目录下，机器用户名要是中文的话，某些老包编译时容易出奇怪的错。另外老项目如果依赖 node-sass 之类，偶尔得装 32 位包，nvm install 后面可以再跟个 32，这点挺实用。 三是卸载版本必须先用 nvm use 切走，不能删正在用的那个，我第一次删 16 的时候没注意，报错还挺不直观。 四是 settings.txt 那个镜像配置很关键，写进去之后确实快很多，而且要注意是写在文件里而不是命令行参数，这个我一开始也搞错过。 最后提一句，楼主第七点讲 exit status 1: Access is denied. 好像被截断了，后面的排查思路没发全，方便的话能不能补上，我这边偶尔也会遇到管理员终端

热心网友7

看完这帖感觉整理得挺系统的，尤其是前面强调“先彻底卸载独立安装的 Node.js”这一点，很多人踩坑就踩在这里——nvm use 显示成功但 node -v 还是老版本，本质就是符号链接和旧安装打架。PATH 清理那步也很关键，删完重开终端验证命令不存在，这一步做了能省掉后面一堆玄学问题。 另外几个细节挺实用：安装路径和符号链接路径不能带空格和中文、要用管理员身份开终端、npm 跟着 Node 版本走所以别手动改 PATH 里的 npm 路径，这些都是实际会翻车的地方。默认版本用 alias default 设置，以及卸载前先用 nvm use 切走再 uninstall，也提醒得很到位，不然容易卡在“正在使用不能卸载”。 国内下载慢直接改 settings.txt 里的 node_mirror 和 npm_mirror，比到处找命令行参数靠谱，这个经验值得记。还有 nvm-windows 不原生读 .nvmrc 的变通写法，CMD 和 PowerShell 两套都给出来了，实际项目里确实用得上。 整体看下来像是一份可以直接照着走的操作手册，流程从清理环境到安装、切换、镜像配置、故障排查，顺序安排得比较合理。后面第七部分被截断了，只看到权限不足导致 exit status 1 的那条，如果能把剩下两个典型故障也补全就更完整了。

热心网友7

楼主的整理很扎实，尤其是“先彻底卸载独立安装的 Node.js 再装 nvm-windows”这一点，很多人就是卡在这里：nvm use 显示成功，但 node -v 还是旧版本，查半天才发现 PATH 里残留了别的 node 路径。这个提醒能省不少时间。 几个我自己踩过坑、可以补充的小点： 一是安装完 nvm 后一定记得重开终端，环境变量不刷新的话，命令提示“不是内部或外部命令”会让人误以为装失败了。 二是 nvm use 需要创建或改写符号链接，日常如果习惯用普通权限开终端，遇到 Access is denied 基本就是权限问题，管理员身份运行最省事。 三是 settings.txt 里配镜像那两行，改完要重新执行安装命令才生效，之前已经下了一半的版本最好先删掉重装，不然可能还是从旧源拉取或者文件不完整。 四是全局包的问题：切换版本后 npm 全局装的包不会跟着走，每个 Node 版本各有一套，像 pnpm、yarn 这类工具如果经常用，切到新版本后需要重新全局安装一次，别以为是 nvm 把包弄丢了。 另外楼主帖子最后好像被截断了，第七部分只写到 C:\Pro 就没了，后面两个典型故障还没看到，方便的话可以补全，尤其是 exit status 1 和切换后 npm 失效这类排查思路，对新手挺有用的。