NVM (Node Version Manager) 完全指南：在 Linux 上管理 Node.js 版本

Node.js 作为前端工程化和后端开发的核心工具，其生态系统飞速发展。但不同项目往往依赖特定版本的 Node.js（例如旧项目需要 Node.js 14，而新项目可能要求 Node.js 20），直接全局安装多个版本会导致冲突。NVM（Node Version Manager） 应运而生，它是一款轻量级的命令行工具，专门用于在单台设备上管理多个 Node.js 版本，支持快速切换、安装、卸载，且完全用户级（无需 sudo），是开发环境必备工具。

目录#

1. 简介#

Node.js 作为前端工程化和后端开发的核心工具，其生态系统飞速发展。但不同项目往往依赖特定版本的 Node.js（例如旧项目需要 Node.js 14，而新项目可能要求 Node.js 20），直接全局安装多个版本会导致冲突。NVM（Node Version Manager） 应运而生，它是一款轻量级的命令行工具，专门用于在单台设备上管理多个 Node.js 版本，支持快速切换、安装、卸载，且完全用户级（无需 sudo），是开发环境必备工具。

2. NVM 安装步骤#

2.1 系统要求#

  • Linux 系统（支持 Ubuntu、CentOS、Debian 等主流发行版）
  • 已安装 curl 或 wget（用于下载安装脚本）
  • 支持的 shell：bash、zsh、fish（推荐 bash 或 zsh）

2.2 安装 NVM#

官方推荐通过 GitHub 脚本安装（确保获取最新版本）：

  1. 打开 NVM 官方仓库，复制最新的安装命令（以下为示例，建议直接访问仓库获取最新链接）：

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

  2. 安装脚本会自动将 NVM 克隆到 ~/.nvm 目录，并在你的 shell 配置文件（如 ~/.bashrc、~/.zshrc 或 ~/.profile）中添加环境变量。

  3. 使配置生效（无需重启终端）：

    # 若使用 bash
source ~/.bashrc
 
# 若使用 zsh
source ~/.zshrc

  4. 验证安装：

    nvm --version  # 输出类似 v0.39.7，表明安装成功

2.3 升级 NVM#

如需更新 NVM 到最新版本：

nvm upgrade

3. 基础命令详解#

NVM 的核心能力通过简洁的命令实现，以下是最常用的基础命令：

3.1 查看可用命令#

nvm help  # 显示所有命令及说明

3.2 安装 Node.js 版本#

# 安装最新稳定版
nvm install node
 
# 安装最新 LTS 版（推荐生产环境使用）
nvm install --lts
 
# 安装指定版本（如 18.17.0）
nvm install 18.17.0
 
# 安装指定 LTS 代号（如 "hydrogen" 对应 Node.js 18 LTS）
nvm install lts/hydrogen

提示：安装完成后，NVM 会自动将该版本设置为当前使用版本（仅当前终端有效）。

3.3 切换 Node.js 版本#

# 使用已安装的指定版本
nvm use 18.17.0
 
# 使用最新版
nvm use node
 
# 使用最新 LTS 版
nvm use --lts

3.4 查看已安装版本#

nvm list  # 或 nvm ls，列出所有已安装版本，当前版本前标有 "->"

示例输出：

->     v18.17.0
       v20.9.0
default -> 18.17.0 (-> v18.17.0)
node -> stable (-> v20.9.0) (default)
stable -> 20.9 (-> v20.9.0) (default)
lts/* -> lts/iron (-> N/A)
lts/iron -> v20.9.0

3.5 设置默认版本#

避免每次打开终端都需 nvm use，可设置默认版本：

nvm alias default 18.17.0  # 将 18.17.0 设置为默认版本

3.6 卸载 Node.js 版本#

nvm uninstall 18.17.0  # 卸载指定版本

3.7 查看远程可用版本#

nvm ls-remote  # 列出所有远程可用版本（较慢，可过滤）
nvm ls-remote --lts  # 仅显示 LTS 版本
nvm ls-remote | grep 18  # 搜索含 "18" 的版本

4. Node.js 版本管理进阶#

4.1 安装 nightly 版本（开发版）#

如需测试最新特性，可安装 nightly 版本：

nvm install nightly  # 安装最新 nightly 版
nvm use nightly      # 切换到 nightly 版

4.2 清理冗余版本#

长期使用后，系统中可能积累多个旧版本，可一键清理：

nvm prune  # 卸载所有未被引用的版本（即非当前使用、非默认版本）

4.3 导出/导入已安装版本#

如需在多台设备同步版本列表：

nvm list > ~/nvm_versions.txt  # 导出已安装版本列表
# 在目标设备执行：
cat ~/nvm_versions.txt | xargs nvm install  # 批量安装列表中的版本

5. 配置与自动化#

5.1 使用 .nvmrc 文件（项目级版本控制）#

为确保团队成员或不同项目使用统一的 Node.js 版本，可在项目根目录创建 .nvmrc 文件：

# 在项目根目录执行
echo "18.17.0" > .nvmrc  # 指定版本
# 或使用 LTS 代号
echo "lts/hydrogen" > .nvmrc

进入项目目录时，NVM 会自动提示切换版本：

cd your-project/
# 输出：Found '.nvmrc' with version <18.17.0>
nvm use  # 无需指定版本，NVM 会读取 .nvmrc 并切换

进阶：配置 shell 自动切换（需手动设置）。例如在 ~/.bashrc 中添加：

cd() {
  builtin cd "$@" || return
  if [[ -f .nvmrc && -r .nvmrc ]]; then
    nvm use
  fi
}

5.2 自定义 NVM 环境变量#

通过环境变量调整 NVM 行为（修改 ~/.bashrc 或 ~/.zshrc）：

# 设置 NVM 安装目录（默认 ~/.nvm）
export NVM_DIR="$HOME/.nvm"
 
# 使用国内镜像加速 Node.js 下载（适用于网络受限场景）
export NVM_NODEJS_ORG_MIRROR="https://npmmirror.com/mirrors/node"

6. 最佳实践#

6.1 生产环境使用 LTS 版本#

LTS（长期支持版）稳定性和安全性更优，推荐用于生产环境：

nvm install --lts  # 安装最新 LTS
nvm alias default lts/*  # 设置最新 LTS 为默认

6.2 避免使用 sudo#

NVM 是用户级工具，安装和使用时绝对不要加 sudo，否则会导致权限冲突（Node.js 会安装到 root 目录，普通用户无法访问）。

6.3 减少全局 npm 包安装#

全局安装的 npm 包（如 npm install -g xxx）会绑定到当前 Node.js 版本，切换版本后需重新安装。建议优先使用项目本地依赖：

# 项目内安装（替代全局安装）
npm install --save-dev eslint  # 本地安装 eslint
npx eslint  # 直接调用本地包（无需全局路径）

6.4 定期更新 NVM 和 Node.js#

nvm upgrade  # 更新 NVM
nvm install --lts --reinstall-packages-from=node  # 安装新版 LTS 并迁移全局包

6.5 清理缓存#

若遇到 npm 安装异常，可清理 NVM 缓存：

nvm cache clear  # 清除 Node.js 安装包缓存

7. 常见问题与 troubleshooting#

7.1 nvm: command not found#

原因：shell 配置文件未加载 NVM 环境变量。
解决：

  1. 确认 ~/.bashrc 或 ~/.zshrc 中存在以下内容： 
    export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # 加载 NVM
  2. 重新加载配置：source ~/.bashrc

7.2 Node.js 安装失败（网络超时）#

原因：官方 Node.js 镜像访问缓慢。
解决：使用国内镜像（参考 5.2 节设置 NVM_NODEJS_ORG_MIRROR）。

7.3 node 命令找不到（已安装但无法使用）#

原因：未切换到已安装版本或未设置默认版本。
解决：

nvm use 18.17.0  # 临时切换
nvm alias default 18.17.0  # 永久设置默认

7.4 权限错误（EACCES: permission denied）#

原因：曾用 sudo 安装 Node.js 或 npm 包，导致文件权限归 root。
解决：

sudo chown -R $USER:$GROUP ~/.nvm  # 修复 NVM 目录权限
sudo chown -R $USER:$GROUP ~/.npm  # 修复 npm 缓存权限

8. 实战示例：多项目版本管理#

假设你同时开发两个项目：

  • 项目 A：依赖 Node.js 16 LTS
  • 项目 B：依赖 Node.js 20 LTS

操作步骤：

  1. 为项目 A 配置版本：

    mkdir project-a && cd project-a
echo "lts/gallium" > .nvmrc  # "gallium" 是 Node.js 16 LTS 代号
nvm use  # 自动安装并切换到 16 LTS
node -v  # 验证：v16.20.2

  2. 为项目 B 配置版本：

    mkdir project-b && cd project-b
echo "20.9.0" > .nvmrc
nvm use  # 安装并切换到 20.9.0
node -v  # 验证：v20.9.0

  3. 切换项目时自动适配：

    cd project-a  # NVM 提示切换到 16 LTS
cd ../project-b  # NVM 提示切换到 20.9.0

9. 参考资料#

通过 NVM，你可以轻松掌控 Node.js 版本，告别“版本冲突”烦恼，专注于项目开发本身。合理使用 .nvmrc 和最佳实践，还能大幅提升团队协作效率！

2025-11