nvm 完全指南：Node.js 多版本安装切换与踩坑排查

你是不是也遇到过这种情况：电脑里一个项目要求 node 14，另一个项目必须 node 18，还有一个新项目直接要 node 22。今天装 18，明天卸掉装 14，后天又要换回 18，卸载的时候还动不动报个 2053 错误，折腾半天代码一行没写。

nvm（Node Version Manager）就是专门解决这个问题的工具。它的作用简单说就是：在你电脑上同时安装多个 node.js 版本，随时切换，互不干扰。装好 nvm 之后，nvm install 18、nvm use 14 这样的命令一敲，版本就切换过去了，再也不用来回卸载重装。

这篇博文我会从下载安装 nvm 开始，把 node.js 安装、版本切换、npm 全局配置、WSL 环境，以及我踩过的各种坑全部写清楚。不管是完全没用过命令行的新手，还是已经装了 node.js 但被版本折腾过的人，按着这篇文章一步步操作，基本都能一次搞定。

1. 为什么每个前端或 Node 开发者都需要 nvm

1.1 多版本并存的真实开发场景

我在实际工作中遇到过几次比较典型的场景，基本能代表大多数人的痛点：

第一类是维护老项目。公司里的旧系统跑在 node 12 或 14 上，升版本可能引发依赖兼容问题，没法轻易升级。但与此同时，你还要用 node 18 甚至 20 去开发新项目。如果电脑里只有一个 node，就只能反复卸载重装，装完新版本后旧项目可能直接跑不起来。

第二类是工具链对版本有严格限制。现在不少脚手架、框架对 node 版本要求越来越苛刻，不仅要求大版本，连小版本都有范围。比如有些工具要求 node 版本在 22.22.3 到 23 之间，或者 24.15.0 到 25 之间，版本低了不行，高了也不认。没有版本管理工具，碰到这种要求只能干瞪眼。

第三类是学习和实验场景。你可能会想试一下最新的 node 特性，但又不想把稳定的开发环境搞乱。用 nvm 装一个最新的 Current 版本，随时随地体验，用完切回 LTS，完全不影响正常开发。

所以 nvm 解决的其实是“多个项目、多个环境、多套依赖”同时存在的核心矛盾。这也是为什么几乎所有前端开源项目的 README 里，都会建议开发者用 nvm 管理 node 版本。

1.2 nvm 是怎么做到“一条命令切换版本”的

很多人第一次听说 nvm，会以为它是个类似虚拟机的工具，把不同 node 版本装进隔离环境里。其实它的原理比想象中简单。

以 Windows 版的 nvm-windows 为例，它管理版本的核心机制是“系统环境变量 + 符号链接（Symbolic Link）”。nvm 安装时会在你指定目录下维护一个版本仓库，比如 D:\nvm，每当你执行 nvm install 18.20.3，它就把对应的 node 完整解压到 D:\nvm\v18.20.3 这样的子目录里。

当你执行 nvm use 18.20.3，nvm 做的操作是：更新 NVM_SYMLINK 指向的路径，让系统里的 node 这个命令实际指向 D:\nvm\v18.20.3\node.exe。

简单类比一下：你的电脑桌面可以同时放好几个版本的软件快捷方式，nvm 就是帮你自动换快捷方式指向的那个工具。真正运行的是哪个程序，取决于当前快捷方式指向哪个目录。

理解了这一点，后面遇到“切换版本后命令行里还是旧版本”这类问题时，排查思路就会清晰很多——大概率是符号链接没有更新，或者环境变量里还有别的 node 路径排在前面。

2. 下载 nvm 前的准备工作与版本选择

2.1 下载前必须确认的 3 件事

在正式安装 nvm 之前，有几件事我建议你先确认一遍，不然装到一半容易翻车。

第一，已经装了 node.js 的话，建议先卸载干净。nvm-windows 安装的时候，如果检测到系统里已有 node，虽然不一定直接报错，但后面容易出现两个东西抢环境变量的问题。比如你装了 nvm 后执行 nvm use，系统里却还留着原来那个 node.exe 的路径，切换可能怎么都不生效。稳妥的做法是：先卸载 node.js，再手动检查一下环境变量里还有没有历史遗留的 node 相关路径，顺便把 C:\Program Files\nodejs 这类残留目录也清掉。

第二，确认你的 Windows 版本和系统位数。nvm-windows 支持 64 位和 32 位系统，下载安装包的时候选对位数就行。如果你的系统太老，比如 Windows 7，要注意一下 nvm-windows 新版可能不再支持，需要找旧版本或者手动安装。

第三，想清楚 nvm 要装在哪个盘。我强烈建议不要装在默认的 C 盘。一方面，node 版本会越来越多，node_modules 也会越来越胖，C 盘很容易被塞满；另一方面，后面装 python 依赖、全局工具时，路径越简单越好。我自己一般装在 D:\nvm 这种根目录级别的路径下，路径中间不要有空格，不要有中文，否则一些工具会识别不了。

2.2 nvm 安装包怎么选：nvm-setup.exe vs nvm-noinstall.zip

nvm-windows 官方 GitHub 仓库（coreybutler/nvm-windows）的 Releases 页面，提供了几个不同格式的安装包，很多人第一次下载时容易看花眼。我直接说结论。

如果你只是想省事，下载 nvm-setup.exe 就行。这是一个图形化的安装向导，双击后一步步点下一步，它会自动帮你设置环境变量、创建符号链接目录，对新手最友好。

如果你想折腾一下，或者想完全掌控安装位置和配置，可以下载 nvm-noinstall.zip。这是一个绿色版压缩包，解压后需要自己手动配置环境变量，并且要手动创建 settings.txt 配置文件。好处是解压即用，想放哪个目录放哪个目录，适合有经验的用户。

另外还会看到 nvm-setup.tar.gz 这种文件，一般是源码包，普通用户不要下，那是给开发者在其他平台上编译用的。

这里特别提醒一句：下载时注意看版本号，选最新的稳定版 Released 文件，别下还在测试阶段的 pre-release 版本。

3. Windows 下 nvm 安装与 node.js 版本管理实操

3.1 nvm-setup.exe 完整安装步骤

下面的步骤我都实际操作过，按这个顺序来基本不会出问题。

第一步，双击运行 nvm-setup.exe。安装程序会先显示一个欢迎界面，直接 Next。

第二步，选择安装路径。这一步最关键。默认路径是 C:\Users\你的用户名\AppData\Roaming\nvm，我建议改成纯英文、无空格的路径，比如 D:\nvm。如果你以后要装很多版本，确保这个盘有足够空间。

第三步，设置 node.js 符号链接路径。安装程序会让你填一个“Node.js Symlink”路径，这是将来 node 命令实际被调用的位置，一般默认是 C:\Program Files\nodejs，也可以改成 D:\nodejs。记住这个路径，后面排查问题用得上。

第四步，确认信息后点击 Install，等待安装完成即可。

安装完之后，程序会自动帮你设置两个环境变量：NVM_HOME（指向 nvm 安装目录）和 NVM_SYMLINK（指向符号链接目录）。同时会把 nvm 安装目录和 %NVM_SYMLINK% 加到系统的 PATH 环境变量里。

打开一个新的命令提示符窗口，输入：

bash复制nvm version

如果能正常输出版本号，比如 1.1.12，说明 nvm 安装成功。

注意：安装完 nvm 后，一定要新开一个命令行窗口，或者重启一下终端，否则环境变量可能不会立即生效。

3.2 用 nvm 安装 node.js 并完成版本切换

nvm 装好之后，下一步就是用它来装 node.js。

先执行：

bash复制nvm list available

这个命令会列出当前所有可以远程安装的 node.js 版本。输出会分成几栏，有 LTS 版本列表、Current 最新版列表等。你可以从里面挑一个稳定的 LTS 版本，毕竟大多数项目都基于 LTS 版本开发。

比如我想装 20.11.1 这个版本：

bash复制nvm install 20.11.1

看到进度条跑完后，再执行：

bash复制nvm use 20.11.1

这时命令提示符窗口会显示“Now using node v20.11.1 (64-bit)”之类的提示，表示切换成功。再用 node -v 验证一下：

bash复制node -v
npm -v

如果两个命令都能正常输出版本，那 node.js 就已经可以正常使用了。

如果你想同时装多个版本，比如还要一个 18.20.4 来维护老项目：

bash复制nvm install 18.20.4
nvm use 18.20.4

以后想切回 20 的话：

bash复制nvm use 20.11.1

想查看当前电脑里已经装了哪些版本，用：

bash复制nvm list

不用那个版本了，可以用：

bash复制nvm uninstall 18.20.4

这一套命令基本覆盖了日常所有版本管理需求。

3.3 验证安装结果和常见命令速查

除了上面几个命令，我再补充几个实际使用频率较高的命令，方便大家对照着看。

我用一个表格把 nvm 高频命令整理出来，平时忘记参数了可以快速翻到这里：

实际验证的时候，我一般会跑三个命令：node -v、npm -v、where node。前两个是确认版本，第三个是确认当前 node 命令到底指向了哪个真实路径。

如果用 where node 查出来的路径不是你设置的那个符号链接目录，那就要注意环境变量里可能有残留的 node 路径在捣乱，优先级比 nvm 的路径还高。这个问题我在后面的常见问题章节里会展开讲。

3.4 nvm 目录下的 settings.txt 与镜像源加速

这里分享一个很容易被忽略但特别实用的点：nvm 安装目录下有一个 settings.txt 文件，里面除了基本的配置，还可以写入下载镜像地址。

如果你发现 nvm install 在国内网络环境下下载非常慢，甚至一直卡在下载中，可以直接编辑 settings.txt，追加两行：

text复制node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

保存后再执行：

bash复制nvm list available
nvm install 20.11.1

下载速度会明显快很多。node 二进制包和 npm 都会从国内镜像拉取，而不是访问外网源。这个配置对所有后续安装的版本都有效，是一劳永逸的优化手段。

4. npm 全局配置与环境变量优化

4.1 先换 npm 镜像源，不然装依赖等到怀疑人生

node.js 装好之后，npm 也自带好了，但直接用默认源下载依赖包在部分网络环境下会非常慢，甚至频繁报错超时。我建议在装任何项目依赖之前，先把 npm 源换成国内镜像。

执行：

bash复制npm config set registry https://registry.npmmirror.com

然后验证一下：

bash复制npm config get registry

如果输出了 https://registry.npmmirror.com，说明镜像源已经生效。

这里插一句：镜像源和 node 下载镜像是两回事。前面改的 settings.txt 是让 nvm 下载 node 本体时走镜像；这里改的是让 npm 下载第三方依赖包时走镜像。两个都建议配好，实际体验会顺畅很多。

如果你有公司内部私有 npm 仓库，也可以把 registry 指到公司地址，原理一样。以后某个项目需要单独用官方源时，可以在项目目录下执行：

bash复制npm config set registry https://registry.npmjs.org

这会把该项目下的 registry 配置覆盖为官方源，不会影响全局设置。

4.2 修改全局包安装路径，别把 C 盘塞爆

默认情况下，执行 npm install -g 安装的全局工具会放在 nvm 当前版本对应的 node 目录下，具体位置是 C:\Program Files\nodejs\node_modules 或者类似路径。这样做的坏处有两个：一是装多了会把 C 盘塞满；二是每次切换 node 版本时，不同版本各自的全局包互不相通，同一个工具可能要在每个版本下重复安装。

我的做法是：把全局包统一放到一个自定义目录，比如 D:\nodejs_global，然后通过环境变量让所有版本都能识别。

操作如下。

先执行：

bash复制npm config set prefix "D:\nodejs_global"
npm config set cache "D:\nodejs_cache"

然后把 D:\nodejs_global 添加到系统环境变量 PATH 中。这样全局安装的 CLI 工具，比如 nodemon、cross-env、vite，都会被放进这个公共目录，并且命令行里可以直接调用。

注意一个细节：从某个 node 版本全局安装的工具，切换到另一个版本后，npm 的全局路径还是指向 D:\nodejs_global，所以工具是共享的。但有些工具内部依赖了特定版本的 node API，换版本后可能行为异常。这种现象不常见，真遇到了就单独在该项目下用 npm install 局部安装一份，不要和全局混用。

还要记得在系统环境变量里添加一个 NODE_PATH，指向全局包目录：

text复制D:\nodejs_global\node_modules

这个变量主要是给老一代工具解析全局模块时用的，现在很多场景用不上了，但加上没坏处。

4.3 node 版本切换与 npm 全局包的关系

用 nvm 切换 node 版本之后，有件事很多人会忽略：全局命令行工具可能需要重新安装，或者至少验证一下能不能正常使用。

原因在于 nvm 切换版本时，当前 shell 的 PATH 路径会从 v20.11.1 切到 v18.20.4，而 npm 全局包如果在某个版本下是独立的，切版本后也许就找不到对应模块了。但如果你按照我上面 4.2 节的做法，把全局路径统一到了 D:\nodejs_global，这个问题基本就不存在了。

我实际使用的体会是：统一全局路径 + 镜像源，配合 nvm，整个 node 多版本管理体验会顺畅非常多。切换版本之后，node -v 变了，但你常用的全局工具依然在那，不用重复安装，也不会动不动就“不是内部或外部命令”。

5. WSL 和 macOS 下的 nvm 安装

5.1 WSL 里安装 nvm

很多人在 Windows 上做开发时，会通过 WSL（Windows Subsystem for Linux）跑 Linux 环境。WSL 里的 node 和 Windows 里的 node 是完全隔离的两个系统，必须是两套安装。有些项目在 WSL 里跑构建脚本，如果里面有 Linux 原生的依赖，就必须在 WSL 里装好 node。

在 WSL 里安装 nvm 跟 Linux 下的安装方式一样，使用官方安装脚本。

打开 WSL 终端，执行：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

或者用 wget：

bash复制wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装脚本会把 nvm 仓库克隆到 ~/.nvm 目录，并自动把相关配置追加到 ~/.bashrc 或 ~/.zshrc 里。

然后重新加载 shell 配置：

bash复制source ~/.bashrc

验证：

bash复制nvm --version

如果提示找不到 nvm，一般是脚本没有正确写入 shell 配置文件。手动在 ~/.bashrc 末尾补充以下内容：

bash复制export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

然后再次 source ~/.bashrc 即可。

后续安装 node 的命令和 Windows 下基本一致：

bash复制nvm install --lts
nvm use --lts

WSL 内安装 nvm 后，Windows 上的 node 和 WSL 内的 node 互不干扰，各自维护版本。哪个环境需要哪个版本，就各自切换，不用来回同步。

5.2 macOS 安装 nvm

macOS 下安装 nvm 也是一行命令的事。

用 curl 安装：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后同样需要把下面几行配置写入 ~/.zshrc（macOS 默认使用 zsh）：

bash复制export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

重启终端或者执行 source ~/.zshrc 后，nvm 命令就可以用了。

安装 node 并切换版本：

bash复制nvm install 20.11.1
nvm use 20.11.1

macOS 下安装 nvm 的好处是，它天然支持不同 shell，而且基于 Unix 的系统下符号链接机制更干净，版本切换比 Windows 更丝滑。不过要注意：如果你用 Homebrew 装过 node，那 brew 版的 node 可能会和 nvm 冲突。建议先把 brew 版的 node 卸载干净，再用 nvm 管理。

6. 高频报错与排查技巧实录

6.1 安装后 node 提示“不是内部或外部命令”

这个问题在 nvm 安装后第一次使用时经常出现。

先说排查思路。执行 nvm version，如果这个能正常输出，说明 nvm 本体没问题。然后检查环境变量里有没有 NVM_SYMLINK 指向的目录（默认是 C:\Program Files\nodejs），并且这个目录在不在 PATH 中。

如果环境变量配置没问题，再看你当前的命令行窗口是不是安装 nvm 之前就打开的。如果是，关掉重开一个终端。环境变量只有在新的终端进程里才会重新读取。

还有一种情况是：nvm use 已经执行成功了，但符号链接目录根本没创建成功，也就是 C:\Program Files\nodejs 这个目录不存在。这时候可以手动执行 nvm use 版本号 让它重建符号链接，或者去 nvm 安装目录下看是否存在对应版本的文件夹。

6.2 nvm install 报错“is not yet released or is not available”

这段报错我在各个技术社区里见过太多次了。典型的信息长这样：

text复制error installing 24.19.0: Node.js v24.19.0 is not yet released or is not available

这个报错的原因很简单：你安装的版本号不存在，或还没发布到镜像源上。

通常有两种情况。一是你手滑拼错了版本号，比如把 20.10.0 写成了 20.1.0。二是你看到了某个版本的预告，或者某篇文章里提到了一个未来版本号，但该版本还没有正式发布到下载源。

解决办法就是先执行：

bash复制nvm list available

从输出里找一个真实存在的版本号，复制过来再执行 nvm install。如果确认版本号没问题但还是报错，那多半是镜像源没同步完整，可以等几分钟再试，或者临时切成官方源试试。

这里提醒一句：不要盲目安装最新版。Current 版本（非 LTS）通常更新频繁、破坏性变更也多，适合尝鲜不适合生产环境。正常开发建议优先装 LTS 版本。

6.3 nvm use 切换后版本没变

执行 nvm use 20.11.1 之后，提示也显示成功了，结果 node -v 输出的还是旧版本号。这是 Windows 下特别容易踩的坑。

排查方向有两个。

第一，检查当前终端是不是管理员权限。nvm-windows 在切换版本时，需要更新符号链接，这个操作在部分 Windows 配置下需要管理员权限。如果权限不足，提示“切换成功”但实际并没有写入成功，然后又弹了个错误被忽略了。解决办法是：用管理员身份重新打开命令提示符或 PowerShell，再执行 nvm use。

第二，检查 PATH 环境变量里有没有多个 node 相关路径。执行：

bash复制where node

如果输出里第一个路径不是 NVM_SYMLINK 指向的目录，说明还有另一个 node 的路径排在前面。常见的原因包括：你之前安装 node 时留下的路径没删干净；或者 PATH 里又手动添加了一个 node 目录。

解决办法是编辑系统环境变量，把旧的 node 路径删掉，只保留 nvm 相关路径。改完记得重启终端。

6.4 卸载 node 时报错 2053

在 Windows 上卸载 node.js 时，有些朋友会遇到错误码 2053 的情况。这个错误通常和 Windows Installer 有关，常见原因是系统中残留了没有清理干净的安装信息，或者 node 相关进程还在运行。

我的处理流程是这样的：

先确认没有 node 相关进程在运行。打开任务管理器，把 node.exe 相关进程全部结束掉。

然后尝试用“程序和功能”正常卸载。如果还是报 2053，可以下载微软官方的程序安装和卸载疑难解答工具（MicrosoftProgram_Install_and_Uninstall.meta.diagcab），运行后选择“卸载”，让它自动修复。

如果这些方法还不行，那就干脆手动清理：卸载后删除 C:\Program Files\nodejs 目录，再在注册表编辑器（regedit）里搜索 nodejs 相关项，把残留的软件信息删掉。改注册表前记得先备份或创建还原点。

如果你已经装了 nvm，更好的做法是不要用 Windows 自带的卸载功能，直接用：

bash复制nvm uninstall <版本号>

这样干净的卸载方式可以避免不少 2053 这类问题。

6.5 某些 GUI 工具提示 node.js not found

有一些编辑器插件、桌面工具，安装或运行时会在系统里查找 node.js 环境，比如提示：

text复制node.js not found (please save below and restart)

这类问题十有八九是因为 nvm 管理的 node 是“按需切换”的，而 GUI 工具没有加载 shell 环境变量，所以找不到。

解决办法是：先在命令行确认 node -v 能正常输出，然后把 NVM_SYMLINK 指向的目录（比如 D:\nodejs）和 npm 全局目录手动加到系统环境变量 PATH 里。这样即使工具不从 shell 启动，也能找到 node。

如果工具找的是某个特定版本，而你已经切换到其他版本了，那就把工具启动时的终端环境切过去，或者在工具设置里把 node 路径直接指定为 D:\nvm\v20.11.1\node.exe。

最后分享几个小技巧

写了一整篇，最后再多说几句实操层面的体会。

第一点，nvm 装好后，平时建议把默认版本固定在一个 LTS 版本上，比如：

bash复制nvm alias default 20.11.1

这样每次新开终端，它都会自动使用这个版本，不用每次手动敲 nvm use。

第二点，node_modules 目录很占空间，切换 node 版本后不一定需要重新安装依赖。但如果你从 node 18 切到 node 20，建议先跑一遍项目的测试脚本，确认没有兼容性问题再继续开发。

第三点，如果你经常在同一台电脑上处理不同项目，可以考虑给每个项目根目录放一个 .nvmrc 文件，里面写上项目要求的 node 版本号。配合 nvm use 可以快速切换。很多 CI 平台也支持读取这个文件来自动选择构建环境，属于一劳永逸的配置习惯。

nvm 的坑基本就这些了。我最初折腾 node 多版本的时候，也是被各种报错折磨了很久，后来把安装路径、环境变量、镜像源这三件事理顺了之后，就再也没在这个上面浪费过时间。希望这篇教程也能帮你彻底告别 node 版本管理问题。