Node.js 版本管理器

项目概述

nvm（Node Version Manager）是一个按用户安装、按 Shell 调用的 Node.js 版本管理工具。它兼容所有 POSIX 标准 Shell（sh、dash、ksh、zsh、bash），支持 Linux、macOS 以及 Windows WSL 环境。通过简单的命令行即可在同一台机器上安装、切换多个 Node.js 版本。

安装与更新

一键脚本

推荐使用官方安装脚本，可通过 curl 或 wget 执行：

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

脚本会克隆仓库到 ~/.nvm，并自动将以下片段写入 Shell 配置文件：

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。追加 --no-use 可推迟加载默认版本；若已使用 zsh 插件管理 nvm，可设 PROFILE=/dev/null 避免修改配置。

Docker 中安装

由于非交互 Shell 不会读取 profile 文件，需借助 BASH_ENV 变量：

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

在 CI/CD 场景下，可通过 ARG NODE_VERSION 配合构建参数灵活指定 Node 版本，并在入口脚本中 source $NVM_DIR/nvm.sh 注入环境。

源码与手动安装

通过 git 克隆仓库并检出最新 tag：

git clone https://github.com/nvm-sh/nvm.git "$NVM_DIR"
cd "$NVM_DIR"
git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`

手动升级只需进入 $NVM_DIR，执行 git fetch --tags origin 后重新检出最新 tag。

验证安装

command -v nvm  # 应输出 nvm

注意 which nvm 不可用，因为 nvm 是 Shell 函数而非可执行文件。Linux 上若提示 command not found，关闭并重启终端，或 source ~/.bashrc / source ~/.zshrc 即可。

核心使用

安装与切换版本

nvm install node      # 安装最新版
nvm install 14.7.0    # 安装指定版本
nvm use 22            # 切换当前 Shell 版本
nvm use node          # 使用已安装最新版
nvm run node --version
nvm exec 4.2 node --version  # 在子 Shell 中执行
nvm which 12.22       # 查看可执行文件路径
nvm alias my_alias v14.4.0  # 自定义别名（不能含空格或斜杠）

首次安装的版本会自动成为新 Shell 的默认值。

特殊别名

• node：最新 node 版本
• iojs：最新 io.js 版本
• lts/* 或 lts/argon：指定 LTS 系列
• current：当前 Shell 激活版本
• system：系统全局安装的 node

LTS 与全局包迁移

LTS 版本可通过 --lts、lts/*、lts/<代号> 指定。安装新版本时迁移全局包：

nvm install --reinstall-packages-from=current 'lts/*'    # 迁移并装 LTS
nvm install --reinstall-packages-from=5 6                # 从 v5 迁到 v6
nvm install --latest-npm 'lts/*'                         # 同时更新 npm

若已在两个已安装版本间迁移，使用 nvm reinstall-packages <源版本>。

离线安装与默认包

--offline 可使用本地缓存安装：

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

在 $NVM_DIR/default-packages 中逐行写入包名，可在每次安装新版本时自动安装，例如 rimraf、object-inspect@1.0.2。

镜像源与 PATH

通过 NVM_NODEJS_ORG_MIRROR、NVM_IOJS_ORG_MIRROR 设置镜像；NVM_SYMLINK_CURRENT=true 可创建 current 符号链接供 IDE 识别。nvm deactivate 可恢复默认 PATH。

颜色与显示

通过 nvm set-colors rgBcm 自定义输出颜色，颜色代码支持红/绿/蓝/青/品红/黄/黑/灰及加粗变体（大小写区分）。持久化可设 export NVM_COLORS='cmgRY'；使用 --no-colors 或 TERM=dumb 关闭彩色输出。

.nvmrc 与 Shell 集成

在项目根目录放置 .nvmrc 写入版本号（如 lts/*、18），可在 bash、zsh、fish 中配置自动调用 nvm use。常用做法是在 shell 配置中加入：

autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$([[ -f ".nvmrc" ]] && echo ".nvmrc" || return)"
  ...
}
add-zsh-hook chpwd load-nvmrc

重要事项

• 从源码安装 node 时需 C++ 编译器，Debian/Ubuntu 需安装 build-essential 与 libssl-dev。
• Apple Silicon 自 v16.0.0 起提供 arm64 预编译包；v14.17.0 起支持源码编译 arm64。
• nvm 自身不原生支持 Fish Shell，亦不支持 Windows 原生环境（需借助 WSL、Git Bash、Cygwin，或替代方案如 nvm-windows、nodist、nvs）。
• Git 版本需 ≥ v1.7.10。
• 不推荐通过 Homebrew 安装 nvm，如已安装请先卸载再使用官方脚本。

卸载

删除 ~/.nvm 目录及 shell 配置文件中的相关 source 行即可完全卸载。