怎么使用 nvm 管理和更新 Node.js 版本

一、nvm 的工作原理与多版本隔离机制

要自如地使用 nvm，首先需要理解它与普通 Node.js 安装方式的本质区别。传统的 Node.js 安装包（如官方 pkg 或 msi 安装程序）会将二进制可执行文件写入系统公共目录（例如 /usr/local/bin/node 或 Windows 的 C:\Program Files odejs），并在全局公用同一套 node_modules 依赖。

这种模式下，当某个新项目需要 Node.js v22 而老项目仍要求运行在 Node.js v18 时，开发者只能被迫反复覆盖安装，导致历史项目构建脚本崩溃。

nvm 则采用物理沙盒隔离 + 环境变量动态注入的架构：

• 物理目录隔离：nvm 将下载的每一个 Node.js 版本存放在独立的子目录中（例如 ~/.nvm/versions/node/v20.18.0/）。每个版本拥有专属于自己的 node、npm、npx 二进制文件以及独立的全局包安装目录。
• 环境变量重定向：当用户在终端输入 nvm use <version> 时，nvm 不会修改系统核心文件，而是将对应版本的 bin 路径动态插入到当前 Shell 会话的 $PATH 变量最前端。这样，系统优先命中的就是所选版本的 Node.js。

二、nvm 的安装与环境初始化

在开始管理版本之前，需要确认本地环境已经正确配置了 nvm 运行脚本。

1. macOS 与 Linux 系统安装

在类 Unix 系统中，官方推荐通过终端运行安装脚本。打开终端并执行以下命令：

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

安装脚本会自动将 nvm 仓库克隆至 ~/.nvm 目录，并尝试在 Shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中写入初始化代码。若安装完成后输入命令未生效，可手动在终端配置文件的末尾添加以下三行：

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 加载 nvm 核心脚本
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # 加载命令补全

保存文件后，在当前窗口重新加载配置：

source ~/.zshrc   # 若使用 bash 则为 source ~/.bashrc

2. Windows 系统特别说明

官方原版 nvm 是为 POSIX 兼容环境（Linux/macOS）编写的 bash 脚本，原生不支持 Windows cmd 或 PowerShell。在 Windows 系统上，应使用社区维护的独立开源工具 nvm-windows（下载 releases 包中的 nvm-setup.exe 安装即可）。其底层通过 Windows 软链接（Symlink）切换目录，日常核心命令与下文介绍的用法基本一致。

3. 校验安装结果

在终端中输入如下诊断命令：

command -v nvm

若终端输出 nvm，说明脚本已被当前 Shell 正确识别加载；注意不要使用 which nvm，因为 nvm 在类 Unix 环境下是一个 Shell 函数而非独立二进制程序。

三、日常版本管理：查看、安装与环境切换

掌握了安装后，日常开发只需熟练运用以下几个核心指令即可应对多版本管理需求。

1. 查询远程官方可用版本

在安装前，可以通过远程查询查看 Node.js 官方发布的所有版本。通常建议重点关注 LTS（长期支持，Long Term Support）版本：

nvm ls-remote --lts

如需查看包括非 LTS、尝鲜版本在内的全部版本清单，可直接执行 nvm ls-remote。

2. 安装特定或最新 LTS 版本

查明目标版本后，执行 nvm install 即可下载并编译/解压对应运行时。支持传入具体版本号、大版本号或 --lts 标识：

nvm install 20.18.0    # 安装指定版本
nvm install 22         # 安装 22.x 系列中最新的小版本
nvm install --lts      # 直接安装最新的官方长期支持版本

安装过程会自动配置与该 Node.js 版本兼容的 npm，无需手动额外安装。

3. 查看本地已安装版本

查看当前主机上已经安装好的全部 Node.js 版本：

nvm ls

列表中箭头 -> 指向的条目代表当前当前终端会话正处于激活状态的版本。

4. 临时切换当前终端会话版本

当需要切换到另一个已安装版本编译或运行特定项目时，使用 nvm use：

nvm use 22.11.0

该操作只会影响当前终端窗口。新开的窗口仍会使用全局默认版本，互不干扰。

5. 设置全局默认版本

如果希望每次打开新终端时都默认使用特定版本，需要通过 nvm alias default 进行固化：

nvm alias default 20.18.0

设置完成后，nvm 会在 ~/.nvm/alias/default 中记录该指向，后续所有新开会话都会自动指向该版本。

四、怎么正确更新 Node.js 版本并迁移依赖

很多开发者在升级 Node.js 时会遇到痛点：在新版本安装完成后，之前在旧版本中全局安装的 pnpm、yarn、typescript、tsx 等命令行工具全部消失了，必须逐一手动重新 npm install -g。

实际上，nvm 专门内置了全局依赖继承参数，可以一步到位实现无损升级。

1. 一键升级并继承旧版本全局包

假设当前主力使用的是 Node.js 20，现在需要更新到 Node.js 22 并将 20 中所有全局包平移到新版本中。只需运行：

nvm install 22 --reinstall-packages-from=20

该命令的工作流程包括三步：

1. 自动在远程仓库抓取 Node.js v22 预编译包并解压入独立目录；
2. 读取 ~/.nvm/versions/node/v20.x/lib/node_modules/ 下已有的全局工具包列表；
3. 在新版本 Node.js 激活的环境中，自动调用新版 npm 将旧版本的包批量重新安装，确保二进制兼容性与原生 C++ 模块重新编译。

2. 切换默认版本并进行验证

安装迁移完成后，将全局默认版本更新至新版本，并检查版本输出：

nvm alias default 22
node -v
npm -v
pnpm -v    # 验证全局包是否可直接调用

3. 安全清理废弃旧版本

新版本在团队项目中运行一段时间、确认所有测试与构建均无兼容性问题后，可以卸载陈旧版本释放硬盘空间：

nvm uninstall 18.20.4

五、团队工程化实战：使用 .nvmrc 锁定项目运行版本

在多人协同或开源项目中，最常见的问题之一就是“代码在我电脑上正常，在同事电脑上报错”。原因往往是两者的 Node.js 大版本不一致（例如新特性语法支持差异、打包工具对 Node API 的废弃等）。

1. 创建 .nvmrc 配置文件

在项目的根目录下创建一个名为 .nvmrc 的文本文件，内容仅需填写项目约定的 Node.js 版本号：

echo "20.18.0" > .nvmrc

也可以填写别名，例如 lts/iron 或 20。将此文件提交至 Git 仓库，即可作为该项目的官方环境标准。

2. 进入目录直接执行 nvm use

当其他团队成员克隆代码并进入项目目录后，无需记忆该项目依赖的具体版本，只需在项目根目录运行：

nvm use

如果该成员本地尚未安装该版本，nvm 会明确提示缺失，此时直接执行 nvm install 即可自动读取 .nvmrc 完成安装。

3. 高级技巧：进入目录自动切换（以 zsh 为例）

如果希望在终端 cd 进入项目目录时自动触发 nvm use，可以在 ~/.zshrc 中加入官方推荐的 Shell Hook：

# 进入包含 .nvmrc 的目录时自动切换
autoload -U add-zsh-hook
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
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

六、高频异常排查与解决方案

1. 重启终端后报 command not found: nvm

原因：Shell 启动时没有自动加载 nvm 的启动脚本。常见于系统升级或默认 Shell 从 bash 切换到 zsh 时。

解决办法：检查当前终端所使用的 Shell（执行 echo $SHELL），若是 /bin/zsh，确保 ~/.zshrc 存在且包含了初始化三行脚本（见本文第二节）；若是 /bin/bash，则写入 ~/.bashrc 或 ~/.bash_profile。

2. nvm install 下载速度慢或因网络超时失败

原因：nvm 默认直连 Node.js 官方服务器，受网络波动影响容易中断。

解决办法：临时或永久指定官方国内镜像加速下载。例如在当前终端设置环境变量：

export NVM_NODEJS_ORG_MIRROR="https://npmmirror.com/mirrors/node"
nvm install 22

3. Windows 下 nvm use 报错 exit status 1 / 拒绝访问

原因：nvm-windows 的原理是在 C:\Program Files odejs 创建指向实际版本的软链接（Symlink），创建软链接需要系统特权。

解决办法：以管理员身份运行 PowerShell 或 CMD；或者在 Windows 10/11 的“开发者设置”中开启“开发者模式”（允许非管理员用户创建符号链接）。此外，安装路径中切勿包含中文字符或空格。

七、常用命令速查表