全栈攻城狮

Appearance

NVM (Node Version Manager) ​

Node.js 版本管理工具 —— 轻松切换和管理多个 Node.js 版本

GitHub（nvm）：https://github.com/nvm-sh/nvm

GitHub（nvm-windows）：https://github.com/coreybutler/nvm-windows

下载：https://github.com/coreybutler/nvm-windows/releases

发展历史 ​

时间事件说明
2010nvm 诞生由 @creationix 创建，最初仅支持 macOS/Linux
2014nvm-windows 出现Corey Butler 发布 nvm-windows，填补 Windows 平台空白
2015TJ 的 n 模块另一个流行的 Node 版本管理工具，与 nvm 并存
2018nvm 广泛采用随着 Node.js 版本迭代加快（每年 2 个大版本），nvm 成为前端标配
2020–2025持续发展nvm-windows 1.1.x 版本稳定，支持 LTS 长期维护。Volta、fnm 等竞品也相继出现
2024nvm-windows 1.2.x性能优化，支持 node 18/20/22 等最新版本

版本管理工具对比 ​

工具平台安装方式特点
nvmmacOS / Linuxcurl/wget最经典，社区最大
nvm-windowsWindowsexe 安装程序Windows 上的 nvm 方案
fnm跨平台静态二进制Rust 编写，更快
Volta跨平台exe / curl自动切换版本，按项目锁定
nmacOS / Linuxnpm 全局安装最简洁，npm 安装

核心特性 ​

特性说明
多版本共存同一台机器安装多个 Node.js 版本，互不干扰
一键切换通过简单命令在不同版本间切换
别名机制为常用版本设置别名（如 nvm alias default 18）
全局 npm 管理切换版本时自动切换对应的 npm
按项目选择配合 .nvmrc 文件，自动读取项目所需版本
LTS 支持快速安装和切换 Node.js LTS 版本

应用场景 ​

场景说明
多项目并行开发不同项目使用不同 Node.js 版本（如 Vue 2 用 16，Vue 3 用 18+）
CI/CD 环境测试多个 Node 版本下的兼容性
本地测试在新版本发布时，快速切换测试项目是否兼容
遗留项目维护老项目需要低版本 Node（如 12/14），新项目需要高版本 18/20+
团队规范使用 .nvmrc 统一团队 Node 版本，避免"在我电脑上能跑"的问题

安装 ​

Windows（nvm-windows） ​

1. 下载安装程序 ​

访问 nvm-windows releases 下载 nvm-setup.exe。

2. 安装 ​

运行安装程序，按提示操作：

安装路径：C:\Users\<用户名>\AppData\Roaming\nvm
Node.js 符号链接路径：C:\Program Files\nodejs

安装后，打开命令提示符（务必以管理员身份运行）验证：

bash
nvm version

3. 配置镜像（国内用户推荐） ​

如果安装了 nvm-windows 1.2.x 或更高版本，设置环境变量 NVM_NODEJS_ORG_MIRROR 为国内镜像，加速 Node.js 下载：

bash
# 通过 nvm 命令设置
nvm node_mirror https://npmmirror.com/mirrors/node/

# 或手动设置环境变量
# 此电脑 → 属性 → 高级系统设置 → 环境变量 → 新建
# 变量名：NVM_NODEJS_ORG_MIRROR
# 变量值：https://npmmirror.com/mirrors/node/

对于低版本 nvm-windows，也可以直接修改 C:\Users\<用户名>\AppData\Roaming\nvm\settings.txt：

txt
root: C:\Users\<用户名>\AppData\Roaming\nvm
path: C:\Program Files\nodejs
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

macOS / Linux（nvm） ​

bash
# 使用安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 或使用 wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装后关闭并重新打开终端，或执行：

bash
source ~/.bashrc   # 或 source ~/.zshrc

常用命令 ​

Windows（nvm-windows） ​

bash
# 查看所有可安装的 Node.js 版本
nvm list available

# 安装指定版本
nvm install 18.20.0
nvm install 20.12.0
nvm install 22.0.0

# 查看已安装版本
nvm list

# 切换到指定版本（当前会话）
nvm use 18.20.0

# 设置默认版本（新终端自动使用）
nvm alias default 18.20.0

# 卸载指定版本
nvm uninstall 20.12.0

# 查看帮助
nvm --help

macOS / Linux（nvm） ​

bash
# 查看所有可安装版本（并过滤）
nvm ls-remote
nvm ls-remote --lts        # 仅 LTS 版本

# 安装指定版本
nvm install 18.20.0        # 安装指定版本
nvm install --lts          # 安装最新的 LTS 版本
nvm install node          # 安装最新稳定版

# 查看已安装版本
nvm ls

# 切换版本
nvm use 18.20.0            # 切换当前 shell 的版本
nvm use --delete-prefix 18 # 修复全局包兼容性

# 设置默认版本
nvm alias default 18.20.0

# 运行指定版本的应用
nvm run 20.12.0 app.js

# 在当前 shell 执行指定版本（不永久切换）
nvm exec 18.20.0 node app.js

.nvmrc 文件 ​

在项目根目录创建 .nvmrc 文件，指定项目所需的 Node.js 版本：

bash
# .nvmrc
18.20.0
# 或使用语义化版本
>18
18.x
--lts

然后进入项目目录时：

bash
# macOS / Linux 自动切换（配合 shell 脚本）
nvm use

# Windows 手动切换
nvm use

自动切换配置（macOS / Linux） ​

在 ~/.zshrc 或 ~/.bashrc 中添加：

bash
# 进入目录时自动读取 .nvmrc
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$(pwd)/.nvmrc"
  if [[ -f "$nvmrc_path" ]]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

常见问题 ​

1. Windows 上切换版本后提示"不是内部或外部命令" ​

原因：当前终端是旧的 cmd 窗口，未刷新 PATH 环境变量。

解决：重新打开命令提示符，或重启终端。

2. npm 版本与 Node 版本不匹配 ​

nvm 会为每个 Node 版本附带对应的 npm 版本。如果需要升级 npm：

bash
nvm use 18.20.0
npm install -g npm@latest

3. 全局 npm 包需要重新安装 ​

切换 Node 版本后，之前版本的全局包不会自动迁移：

bash
# 在旧版本下导出全局包列表
nvm use 16.20.0
npm list -g --depth=0 > global-packages.txt

# 切换到新版本后重新安装
nvm use 18.20.0
# 手动安装需要的全局包
npm install -g yarn pnpm nodemon eslint prettier

4. macOS / Linux：Command not found ​

原因：nvm 未正确加载到 shell 配置中。

解决：确保以下内容在 ~/.bashrc 或 ~/.zshrc 中：

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

参考链接 ​