Windows 系统安装 NVM(Node Version Manager) 的详细步骤如下。请注意,Windows 上的 NVM 通常指的是 nvm-windows 这个开源项目,它与 Linux/macOS 上的原生 nvm 脚本不完全相同(命令和内部机制有差异),但核心功能(安装、切换、管理多个 Node.js 版本)是一样的。
📌 重要准备工作(强烈建议!)
-
卸载现有 Node.js(如果已安装):
- 这是避免冲突的关键步骤!进入 控制面板 -> 程序和功能。
- 找到任何已安装的 Node.js 条目,右键选择 卸载。
- 同时检查安装目录(通常是
C:\Program Files\nodejs或C:\Program Files (x86)\nodejs),如果卸载后文件夹仍然存在,手动删除它。 - 检查环境变量
PATH:按Win + R输入sysdm.cpl-> 高级 -> 环境变量。在 系统变量 或 用户变量 的PATH中,删除任何指向旧 Node.js 安装目录(如C:\Program Files\nodejs\)或 npm 全局包目录(如%AppData%\npm)的条目。保存更改。
-
关闭所有终端/命令行窗口: 包括 CMD、PowerShell、VS Code 的集成终端等。安装过程中会修改环境变量,需要新打开的终端才能生效。
-
下载安装程序:
- 访问 nvm-windows 的官方 Releases 页面: github.com/coreybutler…
- 下载最新的
.exe安装程序。通常文件名类似nvm-setup.exe(推荐)或nvm-setup.zip(解压后运行)。nvm-noinstall.zip是免安装版,需要手动配置,不推荐新手使用。
📍 详细安装步骤 (使用 nvm-setup.exe)
-
运行安装程序:
- 双击下载好的
nvm-setup.exe文件。 - 如果出现 用户账户控制 (UAC) 提示,点击 是。
- 双击下载好的
-
同意许可协议:
- 阅读许可协议,勾选 “I accept the agreement”,点击 Next >。
-
选择安装路径:
- 默认路径: 通常是
C:\Users\<你的用户名>\AppData\Roaming\nvm。强烈建议使用此默认路径! 它位于你的用户目录下,避免权限问题。 - 自定义路径: 如果需要更改,点击 Browse...。务必确保路径中不包含空格或中文字符! (例如
D:\DevTools\nvm是可以的;D:\My Tools\nvm或D:\开发工具\nvm则不行)。选定后点击 Next >。
- 默认路径: 通常是
-
设置 Node.js 的 Symlink 路径:
- 目的: NVM 会在这里创建一个动态的符号链接(symlink)。当你切换 Node 版本时,这个链接会指向你当前使用的 Node.js 版本。这是让系统全局识别
node和npm命令的关键! - 默认路径: 通常是
C:\Program Files\nodejs。这也是之前卸载 Node.js 的那个目录。 - 重要:
- 确保这个路径没有被其他程序占用,并且是空文件夹(如果之前卸载了 Node.js 并手动删除了文件夹,这里应该是空的)。
- 如果该目录存在且非空,安装程序可能会提示覆盖或失败。最好手动确认该目录为空或不存在。
- 点击 Next >。
- 目的: NVM 会在这里创建一个动态的符号链接(symlink)。当你切换 Node 版本时,这个链接会指向你当前使用的 Node.js 版本。这是让系统全局识别
-
确认安装:
- 安装程序会显示你的设置:
Destination Folder: 你选择的 nvm 安装路径。Symlink Folder: 你选择的 Node.js symlink 路径。
- 确认无误后,点击 Next > 开始安装。
- 安装程序会显示你的设置:
-
完成安装:
- 安装完成后,确保 “Run NVM for Windows immediately to verify” 这个选项没有勾选(因为需要新开终端)。直接点击 Finish。
✅ 验证安装与环境配置
-
打开新的终端:
- 按
Win + R,输入cmd或powershell,然后按回车。必须是安装完成后新打开的终端!
- 按
-
检查 NVM 是否安装成功:
- 在命令行中输入:
nvm version - 如果安装成功,会显示你安装的
nvm-windows版本号(例如1.1.12)。这证明nvm命令已可用,且环境变量已正确设置。
- 在命令行中输入:
-
安装 Node.js 版本:
- 安装一个 LTS(长期支持)版本:
nvm install lts - 或者安装一个特定版本(例如 20.13.1):
nvm install 20.13.1 - 国内用户加速(可选但推荐): 如果下载很慢,可以临时使用淘宝镜像:
然后再运行nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/nvm install ...。安装完成后可以重置为官方源(如果不需要):nvm node_mirror https://nodejs.org/dist/ nvm npm_mirror https://github.com/npm/cli/archive/
- 安装一个 LTS(长期支持)版本:
-
查看已安装版本:
nvm list- 会列出所有本地已安装的 Node.js 版本。当前使用的版本前面会有
*标记(但刚安装完可能还没设置默认)。
- 会列出所有本地已安装的 Node.js 版本。当前使用的版本前面会有
-
设置默认/使用某个版本:
- 使用刚安装的版本(例如 20.13.1):
nvm use 20.13.1 - 设置这个版本为默认(新开终端自动使用):
nvm use 20.13.1 nvm on # 确保 nvm 已启用- 注意:
nvm-windows没有alias default命令。nvm use <version>后,该版本在当前用户会话中生效,但nvm-windows会记住最后一次使用的版本,下次新开终端(在同一个用户下)会自动尝试使用它。更可靠的“默认”行为是确保nvm on并且最后一次nvm use的是你想要的版本。
- 注意:
- 使用刚安装的版本(例如 20.13.1):
-
验证 Node 和 npm:
node -v npm -v- 应该分别显示你刚才
use的 Node.js 版本号和对应的 npm 版本号。
- 应该分别显示你刚才
🛠 常用命令 (nvm-windows)
nvm arch [32|64]: 显示当前架构或设置安装 32 位还是 64 位 Node(例如nvm arch 64)。nvm install <version> [arch]: 安装指定版本的 Node(可指定 32/64 位)。nvm list [available]: 列出已安装版本。加available显示可安装的远程版本列表(巨长)。nvm use <version> [arch]: 切换到指定版本(可指定 32/64 位)。nvm on: 启用 nvm(管理 Node 版本)。nvm off: 禁用 nvm(停止管理 Node 版本,恢复系统 PATH 原始状态)。nvm proxy [url]: 设置或查看代理服务器 URL(用于下载)。nvm uninstall <version>: 卸载指定版本的 Node.js。nvm node_mirror [url]: 设置或查看 Node.js 下载镜像 URL(如淘宝镜像)。nvm npm_mirror [url]: 设置或查看 npm 下载镜像 URL(如淘宝镜像)。nvm root [path]: 显示或设置 nvm 的安装路径(一般不轻易改)。
⚠️ 常见问题与注意事项 (Windows 特有)
-
安装失败/命令无效:
- 未卸载旧 Node.js: 这是最常见原因!严格按“准备工作”操作。
- 环境变量冲突: 检查
PATH是否残留旧 Node.js 路径或 npm 全局路径。 - 权限问题: 尝试以管理员身份运行安装程序。安装路径选择用户目录下的默认路径通常能避免权限问题。
- 杀毒软件/防火墙拦截: 临时禁用后再试。
- 路径包含空格/中文: 安装路径和 symlink 路径绝对不能有空格或中文!
- 未开启新终端: 安装或更改配置后,务必关闭所有终端并重新打开一个新的。
-
nvm use后node -v没变/报错:- 权限不足: 确保你不是在需要管理员权限的终端(如 VS Code 以管理员运行)里运行普通用户安装的 nvm。尽量在普通用户权限下使用 nvm。
- 环境变量残留: 再次检查
PATH是否彻底清理干净旧 Node.js 路径。 - Symlink 路径问题: 确认
C:\Program Files\nodejs确实是一个指向nvm安装目录下某个版本的符号链接(快捷方式)。可以打开该目录看看内容是否与nvm目录下的版本文件夹一致。 - 尝试
nvm on: 确保 nvm 处于启用状态。
-
.nvmrc文件:nvm-windows原生不支持像 Linux/macOSnvm那样在目录中运行nvm use自动读取.nvmrc。- 需要借助其他工具或脚本(如
avn的 Windows 版,或自己写个 PowerShell 函数)来实现类似功能。
-
VS Code 集成终端:
- 有时 VS Code 的终端可能不会立即获取到最新的环境变量。如果
nvm use后node -v在 VS Code 终端里没变,尝试:- 完全关闭 VS Code 再重新打开。
- 在 VS Code 终端里运行
refreshenv命令(如果安装了Chocolatey包管理器)。 - 或者简单粗暴地重启电脑。
- 有时 VS Code 的终端可能不会立即获取到最新的环境变量。如果
-
安全卸载
nvm-windows:- 控制面板卸载程序里找到
nvm-windows卸载。 - 手动删除
nvm安装目录(如C:\Users\<用户名>\AppData\Roaming\nvm)。 - 手动删除 Node.js symlink 目录(如
C:\Program Files\nodejs)。 - 检查环境变量
PATH和NVM_HOME、NVM_SYMLINK(如果存在)并删除相关条目。
- 控制面板卸载程序里找到
📣 总结
按照上述步骤,严格卸载旧 Node.js、使用 nvm-setup.exe 安装器、选择无空格/中文的路径、安装后新开终端验证,你就能在 Windows 上顺利使用 nvm-windows 来管理多个 Node.js 版本了。遇到问题首先排查环境变量和旧 Node 残留。