使用 nvm 管理多 Node.js 版本 + pnpm 完整实操，解决 pnpm Node 版本报错

很多前端开发会遇到：老项目必须 Node16，新项目新版 pnpm 要求 Node >=22.13，直接装全局 Node 来回卸载重装非常麻烦。 nvm (Node Version Manager) 可以在本机安装多个 Node 版本，环境互相隔离，一键切换。本文基于 macOS (zsh)，完整演示 nvm 安装 → 多 Node 安装 → 版本切换 → pnpm 安装 → 项目运行，附带 nvm 官方命令手册。解决报错：This version of pnpm requires at least Node.js v22.13

一、简介

什么是 nvm

nvm 全称 Node Version Manager，是 Node.js 版本管理工具。

✅ 本机同时安装多个 Node 版本，版本之间互不冲突
✅ 可以临时切换当前终端 Node 版本，也可以设置终端默认 Node 版本
✅ 不同 Node 环境下的全局包（pnpm/npm）相互隔离

适用场景：一台电脑维护多个前端项目，不同项目要求 Node 版本不一样（老项目 Node16、新项目 Node24）

二、安装 nvm

1. 执行官方安装脚本

复制代码

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

可以去 nvm github 主页查看最新版本号，替换脚本内版本

2. 配置环境变量

安装完成后，需要把 nvm 配置写入 zsh 配置文件 ~/.zshrc

复制代码

vim ~/.zshrc

在文件末尾追加下面配置：

复制代码

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

保存退出 vim，执行 source 命令，让配置立即生效：

复制代码

source ~/.zshrc

3. 验证 nvm 是否安装成功

复制代码

nvm --version

输出版本号 0.37.2 即代表安装成功。

常见坑：新开终端提示 nvm: command not found 原因：配置没有放在.zshrc文件末尾，或者没有 source 生效。重新执行source ~/.zshrc，完全关闭终端再打开测试。

三、安装多个 Node.js 版本

1. 查看远程可安装的 Node 版本

复制代码

# 列出所有远程可用版本
nvm ls-remote

# 只查看LTS长期支持版本
nvm ls-remote --lts

2. 安装需要的 Node 版本

示例：安装 v16.19.1（老项目）、v24.22（新项目，适配新版 pnpm）

复制代码

# 安装 node16.19.1
nvm install 16.19.1

# 安装 node24.22
nvm install 24.22

nvm 安装 Node 时，会自动附带安装对应版本的 npm。

3. 查看本地已经安装的 Node 列表

复制代码

nvm ls

输出列表中，-> 指向的版本，就是当前终端正在激活使用的 Node 版本。

四、Node 版本切换 & 设置默认版本（核心）

重点区分两个命令：

nvm use <版本号>：临时切换，仅当前终端生效，关闭终端失效

nvm alias default <版本号>：设置默认版本，所有新打开终端自动加载该 Node

复制代码

# 临时切换到 node16（当前终端生效）
nvm use 16.19.1

# 临时切换到 node24（当前终端生效）
nvm use 24.22

# 设置新开终端默认使用 node24
nvm alias default 24.22

# 设置新开终端默认使用 node16
nvm alias default 16.19.1

版本别名简化（推荐）

可以自定义别名，不用每次输入完整版本号

复制代码

# 创建别名
nvm alias node16 16.19.1
nvm alias node24 24.22

# 一键切换
nvm use node16
nvm use node24

# 设置默认
nvm alias default node24

验证：关闭终端，重新打开，执行 node -v，输出就是 default 设置的版本。注意：已经打开的旧终端窗口不会自动变更默认版本，需要手动nvm use或者重启终端。

五、安装 pnpm

⚠️ 重要知识点：pnpm 跟随当前激活的 Node 环境安装！切换到哪个 node 版本，就在当前环境安装 pnpm；不同 Node 环境全局 pnpm 互相隔离。新版 pnpm 对 Node 最低版本有强制要求，低版本 Node 执行新版 pnpm 就会报版本错误。

安装 pnpm

复制代码

# 先切换到高版本Node（新版pnpm要求Node>=22.13）
nvm use node24

# 执行pnpm官方安装脚本
curl -fsSL https://get.pnpm.io/install.sh | sh -

安装完成，重启终端，验证：

复制代码

pnpm -v

报错场景：This version of pnpm requires at least Node.js v22.13

原因：当前终端激活的 Node 版本过低（比如 node16），新版 pnpm 不支持。 ✅ 解决方案：执行 nvm use node24 切换高版本 Node，再执行 pnpm 命令。

六、运行前端项目

1. 手动切换版本运行项目

复制代码

# 进入项目目录
cd /xxx/your-project

# 切换项目需要的node版本
nvm use node24

# 安装依赖
pnpm install

# 执行项目命令（示例：reinstall / dev / build）
pnpm run reinstall
pnpm run dev
pnpm run build

进阶：项目目录自动切换 Node 版本（.nvmrc）

适合多项目开发，进入项目目录自动切换对应 Node，离开项目自动切回全局 default 版本。

在项目根目录新建 .nvmrc 文件，文件内只写一行

24.22
在 ~/.zshrc 文件末尾追加自动切换脚本

nvm auto switch

load-nvmrc() {
local nvmrc_path=" $(nvm_find_nvmrc)" if [ -n "$ nvmrc_path" ]; then
local nvmrc_node_version= $(nvm version "$ (cat " ${nvmrc_path}")") if [ "$ nvmrc_node_version" = "N/A" ]; then
nvm install
elif [ " $nvmrc_node_version" != "$ (nvm version)" ]; then
nvm use
fi
elif [ -n " $(PWD=$ OLDPWD nvm_find_nvmrc)" ] && [ " $(nvm version)" != "$ (nvm version default)" ]; then
echo "Reverting to default node"
nvm use default
fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc
生效配置

source ~/.zshrc

使用效果：cd 进入项目目录，自动执行nvm use；cd 退出项目目录，自动切回全局默认 Node 版本。

七、nvm 常用精简命令（快速查阅）

复制代码

nvm --version                 # 查看nvm版本
nvm ls                        # 查看本地已安装node列表
nvm ls-remote                 # 查看远程可安装node版本
nvm install x.x.x             # 安装指定node版本
nvm use x.x.x                 # 当前终端切换node版本
nvm alias default x.x.x       # 设置新开终端默认node
nvm alias 别名 版本号          # 自定义版本别名
nvm uninstall x.x.x           # 删除指定node版本
node -v                       # 查看当前node版本
npm -v                        # 查看当前npm版本
pnpm -v                       # 查看当前pnpm版本

八、nvm v0.37.2 完整官方命令手册（参考资料）

执行 nvm --help 可以查看原版帮助文档，下面附带中文说明。 <version> 代表 nvm 识别的版本字符串，可以是完整 / 部分版本号、内置别名、自定义别名。

版本号：0.10、v0.1.2、v1（v 前缀可选）

内置别名：node、stable、unstable、iojs、system

自定义别名：nvm alias 名称版本

复制代码

# 基础信息
nvm --help                                  # 展示帮助文档
    --no-colors                             # 关闭彩色输出
nvm --version                               # 打印nvm版本

# 安装卸载 Node
nvm install [<version>]                     # 下载并安装指定Node版本，省略版本读取.nvmrc
    -s                                      # 源码编译安装，不下载预编译包
    --reinstall-packages-from=<version>     # 安装新版本，迁移旧版本全局包
    --lts                                   # 仅安装LTS长期支持版
    --lts=<LTS name>                        # 安装指定系列LTS
    --skip-default-packages                 # 跳过default-packages文件
    --latest-npm                            # 安装Node后自动升级npm
    --no-progress                           # 关闭下载进度条
    --alias=<name>                          # 安装完成设置别名
    --default                               # 安装完成直接设置为default默认版本

nvm uninstall <version>                     # 卸载指定Node版本
nvm uninstall --lts                         # 卸载lts/*别名对应的版本
nvm uninstall --lts=<LTS name>              # 卸载指定LTS系列版本

# 版本切换 & 执行命令
nvm use [<version>]                         # 修改shell PATH切换Node，省略版本读取.nvmrc
    --silent                                # 静默输出
    --lts                                   # 使用lts/*版本
    --lts=<LTS name>                        # 使用指定LTS系列

nvm exec [<version>] [<command>]            # 在指定Node环境执行一条命令，不切换当前shell
    --silent
    --lts
    --lts=<LTS name>

nvm run [<version>] [<args>]                # 使用指定node版本直接运行node脚本
    --silent
    --lts
    --lts=<LTS name>

nvm current                                 # 查看当前激活Node版本

# 版本列表查询
nvm ls [<version>]                          # 列出本地已安装Node
    --no-colors
    --no-alias                              # 不展示别名
nvm ls-remote [<version>]                   # 列出远程可安装Node
    --lts                                   # 只展示LTS版本
    --lts=<LTS name>
    --no-colors

nvm version <version>                       # 将别名/模糊版本解析为本地真实版本号
nvm version-remote <version>                # 解析远程对应的版本号
    --lts
    --lts=<LTS name>

# 别名管理
nvm alias [<pattern>]                       # 查看匹配的所有别名
    --no-colors
nvm alias <name> <version>                  # 创建/修改别名
nvm unalias <name>                          # 删除自定义别名

# 全局包迁移
nvm install-latest-npm                      # 在当前node环境升级npm
nvm reinstall-packages <version>            # 将旧版本全局包重装到当前Node

# 环境控制
nvm deactivate                              # 当前shell取消nvm环境，还原PATH
    --silent
nvm unload                                  # 完全从shell卸载nvm

# 路径、缓存
nvm which [current | <version>]             # 查看node版本的实际文件路径
    --silent
nvm cache dir                               # 查看nvm缓存目录
nvm cache clear                             # 清空nvm下载缓存

# 终端配色
nvm set-colors [<color codes>]              # 设置终端文字颜色

官方示例

复制代码

nvm install 8.0.0                     # 安装指定完整版本
nvm use 8.0                           # 使用本地已安装最新8.0.x
nvm run 6.10.3 app.js                 # 使用node6.10.3直接运行app.js
nvm exec 4.8.3 node app.js            # 在node4.8.3环境执行命令，不切换当前终端
nvm alias default 8.1.0               # 设置新开终端默认node版本
nvm alias default node                # 默认使用本地最新安装node

nvm install node                      # 安装最新正式版node
nvm use node                          # 使用本地最新node
nvm install --lts                     # 安装最新LTS长期支持版本
nvm use --lts                         # 使用最新LTS版本

nvm set-colors cgYmW                  # 修改nvm输出文字配色

卸载 nvm：直接删除 ~/.nvm 目录，即可彻底移除 nvm。

九、FAQ

Q1：nvm 切换 Node 后，pnpm 为什么跟着变？

A：nvm 本质是修改 shell 的 PATH 环境变量。不同 Node 版本的全局包相互隔离，切换 Node 后，全局 pnpm/npm 环境自动切换。

Q2：设置 default 默认版本后，已经打开的终端会自动切换吗？

A：不会。nvm alias default 只对新打开的终端生效 ，已经打开的终端需要手动执行nvm use或者重启终端。

Q3：pnpm 提示 node 版本过低怎么处理？

A：新版 pnpm 对 Node 最低版本有强制要求，可以查看官方兼容列表：https://r.pnpm.io/comp。两种方案：①切换高版本 Node；②降级 pnpm 版本适配低版本 Node（不推荐长期使用）。

Q4：新开终端提示 nvm command not found？

A：检查.zshrc配置是否写在文件末尾，执行source ~/.zshrc，关闭终端重新打开。

Q5：nvm v0.37.2 和网上 v0.39 版本命令差异大吗？

A：日常开发核心命令完全一致，nvm install / nvm use / nvm alias default、.nvmrc自动识别全部支持。仅少量高级参数存在差异，不影响前端项目开发。

十、小结

nvm 实现多 Node 版本共存，各个环境互相隔离，解决多项目 Node 版本冲突问题。
nvm use临时切换；nvm alias default设置新开终端默认 Node。
pnpm 安装绑定当前激活 Node 环境，低版本 Node 无法运行新版 pnpm。
多项目维护推荐搭配，nvmrc自动切换 Node，省去每次手动敲命令。

使用 nvm 管理多 Node.js 版本 + pnpm 完整实操，解决 pnpm Node 版本报错

一、简介

什么是 nvm

二、安装 nvm

1. 执行官方安装脚本

2. 配置环境变量

3. 验证 nvm 是否安装成功

三、安装多个 Node.js 版本

1. 查看远程可安装的 Node 版本

2. 安装需要的 Node 版本

3. 查看本地已经安装的 Node 列表

四、Node 版本切换 & 设置默认版本（核心）

版本别名简化（推荐）

五、安装 pnpm

安装 pnpm

报错场景：This version of pnpm requires at least Node.js v22.13

六、运行前端项目

1. 手动切换版本运行项目

进阶：项目目录自动切换 Node 版本（.nvmrc）

nvm auto switch

七、nvm 常用精简命令（快速查阅）

八、nvm v0.37.2 完整官方命令手册（参考资料）

官方示例

九、FAQ

Q1：nvm 切换 Node 后，pnpm 为什么跟着变？

Q2：设置 default 默认版本后，已经打开的终端会自动切换吗？

Q3：pnpm 提示 node 版本过低怎么处理？

Q4：新开终端提示 nvm command not found？

Q5：nvm v0.37.2 和网上 v0.39 版本命令差异大吗？

十、小结