Node.js 版本管理器

nvm 简介

nvm（Node Version Manager）是一个面向 Node.js 的版本管理工具，采用按用户安装、按 shell 调用的方式工作。它可在任意符合 POSIX 标准的 shell（sh、dash、ksh、zsh、bash）上运行，支持 Unix、macOS 以及 Windows WSL 环境。通过 nvm，开发者能够在同一台机器上快速安装、切换多个 Node.js 版本，避免因项目间版本差异带来的兼容性问题。

核心特性

• 安装、卸载任意版本的 Node.js 与 io.js
• 通过 .nvmrc 文件锁定项目级 Node 版本
• 支持 LTS（长期支持）别名，例如 lts/*、lts/argon
• 跨版本迁移全局 npm 包
• 离线安装已缓存的版本
• 自定义输出颜色、镜像源、授权头等

安装与更新

官方推荐通过安装脚本进行安装或更新：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
# 或
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

脚本会将仓库克隆到 ~/.nvm（若设置了 $XDG_CONFIG_HOME 则克隆到该目录下），并尝试将以下片段写入对应的 profile 文件（~/.bashrc、~/.bash_profile、~/.zshrc 或 ~/.profile）：

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

可通过环境变量 NVM_SOURCE、NVM_DIR、PROFILE、NODE_VERSION 自定义安装源、目录、配置文件与版本。若不希望脚本修改 shell 配置，可设置 PROFILE=/dev/null。

Docker 中安装

Docker 容器通常以非交互方式运行 bash，不会读取常规 profile 文件，因此需要借助 BASH_ENV：

SHELL ["/bin/bash", "-o", "pipefail", "-c"]
ENV BASH_ENV "${HOME}/.bash_env"
RUN touch "${BASH_ENV}"
RUN echo '. "${BASH_ENV}"' >> ~/.bashrc
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | PROFILE="${BASH_ENV}" bash
RUN echo node > .nvmrc
RUN nvm install

对于 CI/CD 场景，可使用更稳健的方式：

FROM ubuntu:latest
ARG NODE_VERSION=20
RUN apt update && apt install curl -y
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
ENV NVM_DIR=/root/.nvm
RUN bash -c "source $NVM_DIR/nvm.sh && nvm install $NODE_VERSION"
ENTRYPOINT ["bash", "-c", "source $NVM_DIR/nvm.sh && exec \"$@\"", "--"]
CMD ["/bin/bash"]

可通过 --build-arg NODE_VERSION=19 覆盖默认版本。

验证安装

command -v nvm

输出 nvm 即表示成功。注意 which nvm 不会生效，因为 nvm 是通过 source 加载的 shell 函数。

基本使用

nvm install node        # 安装最新版本
nvm install 14.7.0      # 安装指定版本
nvm alias my_alias v14.4.0   # 设置别名
nvm use node            # 切换版本
nvm run node --version  # 在指定版本下执行
nvm exec 4.2 node --version   # 在子 shell 中执行
nvm which 12.22         # 查看可执行文件路径
nvm ls                  # 列出已安装版本
nvm ls-remote           # 列出可安装版本

install、use、run、exec、which 等命令均支持特殊别名：node、iojs、current、system 等。

长期支持与版本迁移

可使用 LTS 别名安装或切换到指定的 LTS 线：

nvm install --lts
nvm install --lts=argon
nvm install 'lts/*'

在新版本安装时迁移已有的全局 npm 包：

nvm install --reinstall-packages-from=current node
nvm install --reinstall-packages-from=5 6

若希望同时升级 npm，可附加 --latest-npm。在已安装版本之间迁移包，可使用独立的 reinstall-packages 子命令：

nvm use 22.22.2
nvm reinstall-packages 22.20.0

离线安装与默认全局包

通过 --offline 标志可避免联网，仅使用本地缓存：

nvm install --offline 14.7.0
nvm install --offline --lts

若希望在每次安装新版本时自动安装一组全局包，可在 $NVM_DIR/default-packages 中逐行列出：

rimraf
object-inspect@1.0.2
stevemao/left-pad

镜像源、版本文件与 PATH

通过 $NVM_NODEJS_ORG_MIRROR 与 $NVM_IOJS_ORG_MIRROR 可指定自定义镜像；通过 $NVM_AUTH_HEADER 可为镜像请求附带授权头：

NVM_AUTH_HEADER="Bearer secret-token" nvm install node

项目根目录下的 .nvmrc 文件可声明所需版本，nvm use、nvm install、nvm which 在未显式指定版本时会读取该文件。

设置默认 Node 版本：

nvm alias default node
nvm alias default 18

恢复系统 PATH：

nvm deactivate

兼容性提示

• macOS 自 10.15 起默认 shell 为 zsh，需确保 ~/.zshrc 存在后再运行安装脚本。
• Apple Silicon 机器建议使用 Node.js v16.0.0 及以上版本以获得 arm64 支持。
• 不支持 Fish shell，但社区提供多种替代插件。
• Homebrew 安装方式不受官方支持。
• 在 Windows 上需借助 WSL、Git Bash 或 Cygwin，否则应使用 nvm-windows、nodist 或 nvs 等替代方案。