Skip to content

nvm-windows 2.x 安装以及使用 ​

前言 ​

2023 年 6 月 20 日,nvm-windows 的作者与合作开发者开始全职开发后继项目 Runtime,NVM for Windows 随后进入 功能开发冻结(feature development freeze) 阶段。此后,原项目主要进行缺陷修复和必要更新;新功能建议则被标记为 consider for rt,留待 Runtime 评估。

原本期待着 Runtime,没想到先等来了 NVM for Windows v2:2026 年 8 月 29 日,首个候选版 v2.0.0-rc.1 发布;同年 9 月 2 日,正式版 v2.0.0 发布。那么,Runtime 怎么样了?

根据官方 Runtime Wiki,2026 年 3 月,针对 npm 生态及个人维护者的攻击日益增多,JavaScript 生态面临更突出的信任与安全问题。官方给出的原因主要有两点:

  • Runtime 当时正处于转型阶段,无法及时补上这一缺口;
  • NVM for Windows 已具备用户基础和明确的项目定位,更适合快速承载这些能力。

因此,团队暂停 Runtime,将开发重心转向 NVM for Windows v2,并复用了 Runtime 已有的部分成果。

简介 ​

TIP

nvm-windows v2 是一款专为 Windows 平台设计的 Node.js 版本管理工具,支持在同一台计算机上安装和管理多个 Node.js 版本,并可根据不同项目的需求快速切换,从而减少版本不一致带来的兼容性问题。

2.x 的主要变化 ​

2.x 不是 1.x 的普通小更新,而是一次整体重写。对个人开发者来说,比较重要的变化包括:

  • 不再强制要求管理员权限。
  • 引入 Shim 模式和 Link 模式。
  • 支持 .nvmrc、.node-version 和 package.json 等项目版本声明。
  • Shim 模式下可以根据当前目录自动选择 Node.js 版本。
  • 可以自动安装项目要求但本机尚未安装的版本。
  • 支持并行安装、下载缓存和更小的 7z 安装包。
  • 可以配置安装新 Node.js 版本时自动安装指定的全局包。

下载以及相关文档 ​

官方文档

项目地址

nvm-windows 2.x 新功能

版本解析与项目固定版本

官方升级指南

NVM for Windows Releases

设备相应安装包
基于 x64 的处理器x64-setup.exe
基于 ARM64 的处理器arm64-setup.exe

安装 ​

对于受支持的 1.x 安装,推荐通过 2.x 安装器完成迁移:另外,v1.1.7 以下不支持自动迁移,需要先备份再卸载旧版;v1.1.7 及以上则可以直接升级。

CAUTION

如果从1.x升级安装前请务必完成以下准备:

  1. 备份重要配置,并记录当前版本和全局包。
  2. 使用普通用户身份运行 Community 2.x 安装器。
  3. 在向导中确认版本存储位置和迁移选项。
  4. 安装完成后打开新的终端。
  5. 检查版本、命令来源和实际 Node.js 版本。
  1. 同意许可协议,点击 Next

nvm_install

  1. 选择 Node.js 存储位置,该目录路径是用于保存下载各个 Node.js版本的目录,点击 Next

nvm_install

  1. 操作模式,推荐 Shim 模式,点击 Next

nvm_install

  1. 配置默认设置,按自己的情况进行设置即可,点击 Next

nvm_install

  1. 订阅作者软件更新信息,如果不需要的,留空即可,点击 Next

nvm_install

  1. 确认自己配置信息,确认无误点击 install

nvm_install

  1. 安装完毕

nvm_install

常用指令 ​

安装与卸载

powershell
nvm install lts             # 安装最新 LTS 版,推荐
nvm install latest          # 安装最新稳定版
nvm install 22              # 安装 Node.js 22 的匹配版本
nvm install 22.14.0         # 安装指定版本
nvm install 20 22 24        # 一次安装多个版本
nvm uninstall 22            # 卸载 Node.js 22
nvm uninstall 22 --purge    # 卸载并删除对应下载缓存

查看与切换版本

powershell
nvm list                    # 查看已安装版本
nvm ls                      # nvm list 的简写
nvm list releases           # 查看可下载版本
nvm use 22                  # 切换到 Node.js 22
nvm use lts                 # 使用最新 LTS 版本
nvm use latest              # 使用本机已安装的最高版本
nvm use last                # 返回上一次使用的版本
nvm default                 # 查看当前默认版本

项目版本管理

powershell
nvm pin                     # 将当前版本写入项目版本文件
nvm pin 22                  # 将 Node.js 22 写入 .nvmrc
nvm pin 22 --file=package.json

在 shim 模式并开启自动检测后,进入包含 .nvmrc 等文件的项目目录,NVM 可以自动识别项目所需版本。

别名

powershell
nvm alias add work 22       # 创建别名 work
nvm alias list              # 查看别名
nvm alias remove work       # 删除别名
nvm use work                # 使用别名对应的版本

配置与故障排查

powershell
nvm config list             # 查看当前配置
nvm config get mode         # 查看运行模式
nvm env                     # 查看安装路径、版本和镜像等环境信息
nvm doctor                  # 检查常见问题
nvm doctor --autofix        # 自动修复支持修复的问题

NVM 自身

powershell
nvm --version               # 查看 NVM 版本
nvm upgrade --check         # 检查 NVM 是否有更新
nvm upgrade                 # 升级 NVM
nvm off                     # 暂停 NVM 管理,不删除 Node.js
nvm on                      # 恢复 NVM 管理

按项目自动选择 Node.js 版本 ​

使用 .nvmrc 固定版本 ​

在项目根目录创建 .nvmrc,写入项目要求的版本,例如:

text
24.20.0

进入项目目录后,通过实际命令验证:

powershell
node --version

如果 Shim 的自动版本解析已启用,并且该版本已经安装,项目中的 node 就会使用 24.20.0。离开项目且没有其他版本声明时,则使用默认版本。

也可以使用 NVM 提供的命令生成版本声明文件:

powershell
nvm pin 24 --file=.nvmrc

nvm pin 会将解析后的具体版本写入指定文件。版本声明文件通常应随项目提交,这样其他开发者也能知道项目要求的 Node.js 版本。

支持哪些版本声明 ​

默认情况下,NVM for Windows 2.x 可以检查:

  1. .nvmrc
  2. .node-version
  3. package.json 中的 engines.node

它们可以是具体版本,也可以是版本范围。需要注意,版本范围不一定意味着始终选择最高版本。例如默认版本已经满足 engines.node 的范围时,NVM 可以继续使用默认版本。

如果项目需要可重复的准确环境,建议使用具体版本,而不是只写宽泛的范围。

如何确认 Shim 实际选择了哪个版本 ​

nvm list 和 nvm default 显示的是默认版本,不一定等于当前项目目录实际运行的版本。可以使用:

powershell
node --nvm-which --version
npm --nvm-which --version

输出会说明版本来源、解析结果和实际 Node.js 路径,适合排查“为什么没有使用项目版本”的问题。

能否同时运行不同版本 ​

可以。在不同项目目录或不同终端中,Shim 可以分别解析版本。例如一个旧项目使用 Node.js 18,另一个新项目使用 Node.js 24,两者的进程可以同时运行。

已经启动的 Node.js 进程不会因为之后切换默认版本而改变;新版本选择只影响之后启动的进程。

按 Node.js 版本管理全局包 ​

在使用多个 Node.js 版本时,不建议再把“配置共享全局目录”作为必做步骤。不同版本共用全局包,虽然减少了重复安装,但也可能带来依赖兼容性、工具版本不一致和 PATH 冲突等问题。

在默认配置下,NVM for Windows v2 会按 Node.js 版本管理全局包。对于少量跨项目常用的命令行工具,可以通过 auto_installed_modules 预先约定一份默认安装清单:

powershell
nvm config set auto_installed_modules=pnpm,typescript

之后安装新的 Node.js 版本时,NVM 会自动为该版本安装清单中的全局包:

powershell
nvm install lts
nvm use lts

可以通过以下命令查看当前清单:

powershell
nvm config get auto_installed_modules

需要注意的是,auto_installed_modules 只对之后新安装的 Node.js 版本生效。已有版本如需补齐工具,可以切换版本后手动安装:

powershell
nvm use 22
npm install -g pnpm typescript

对于 TypeScript、ESLint、Prettier 等主要由具体项目使用的工具,更推荐将它们记录到项目的 devDependencies 中,通过 npm scripts 或 npx 调用。全局清单只保留少量跨项目通用的工具即可 。

[!TIP] auto_installed_modules 用于设置新 Node.js 版本默认安装的全局包,与控制是否自动安装缺失 Node.js 版本的 auto_install 是两个独立配置。

总体来说,更推荐“项目工具随项目管理,通用工具按 Node.js 版本管理”,而不是让所有 Node.js 版本共享同一个全局目录。

常见问题排查 ​

node 或 npm 没有使用预期版本 ​

先检查命令来源:

powershell
(Get-Command node -All).Source
(Get-Command npm -All).Source

再检查 Shim 的实际解析结果:

powershell
node --nvm-which --version

如果 PATH 中某个具体 Node.js 版本目录排在 .nodejs 前面,就可能绕过 Shim。应同时区分永久 PATH 和当前进程继承的临时 PATH,不要只凭一次报警就认定安装损坏。

修改配置后没有生效 ​

关闭旧终端并打开新的终端再验证。已经运行的程序通常仍保留启动时继承的环境,不会因为永久 PATH 已修改就自动更新。

nvm doctor 应该什么时候使用 ​

nvm doctor 可用于检查环境,但应先结合当前 Shell、PATH 和命令来源理解结果。Git Bash 等不受支持的 Shell 环境可能让诊断结果与正常 PowerShell 会话不同。

nvm doctor --autofix 属于修复操作,可能改变环境,不应和只读检查混为一谈。执行修复前应确认自己了解要修改的内容,并做好备份。

是否还需要管理员权限 ​

2.x 不再强制要求管理员权限。不要沿用 1.x 教程中“所有命令都先用管理员终端执行”的习惯;是否需要提升权限,应根据具体操作和官方提示判断。

nvm-windows 和 fnm 怎么选 ​

两者目前都在持续维护,也都能管理多个 Node.js 版本。

  • 如果只使用 Windows,希望使用安装器、Windows 集成和 nvm-windows 2.x 的 Shim 能力,可以继续选择 nvm-windows。
  • 如果经常使用 Windows、Linux 和 macOS,希望统一命令与配置体验,可以优先考虑 fnm。
  • 如果现有 nvm-windows 2.x 已能满足项目需求,就没有必要仅因为性能宣传而迁移。

版本管理器只负责选择 Node.js,不会直接让 Node.js 程序或项目构建获得数量级提速。网上常见的“fnm 比 nvm 快数十倍”通常是与 Shell 脚本版 nvm-sh 的旧测试,不能直接套用到 nvm-windows 2.x。

无论选择哪个工具,项目中保留明确的版本声明,通常比强求所有设备使用同一个版本管理器更重要。

Last updated: