Linux 下安装与使用 NVM（Node Version Manager）全指南

目录#

1. 什么是 NVM？
2. 安装前准备
3. NVM 安装步骤
4. 验证 NVM 安装
5. NVM 常用命令详解
6. NVM 常见使用场景
7. NVM 最佳实践
8. 常见问题与故障排除
9. 总结
10. 参考资料

1. 什么是 NVM？#

NVM（Node Version Manager）是一个开源的命令行工具，用于管理 Node.js 版本。它的核心功能包括：

• 多版本安装：同时安装多个 Node.js 版本（如 v16、v18、v20）。
• 快速切换：在不同 Node.js 版本间一键切换，支持全局默认版本和项目局部版本。
• 版本隔离：每个 Node.js 版本的全局包（如 npm、yarn）独立存储，避免版本冲突。
• 无权限问题：所有操作基于用户目录（~/.nvm），无需 sudo 权限。

注意：NVM 仅支持 Linux 和 macOS，Windows 用户可使用 nvm-windows（非官方，但功能类似）。

2. 安装前准备#

在安装 NVM 前，请确保系统满足以下条件：

2.1 系统要求#

• Linux 发行版（如 Ubuntu、Debian、CentOS、Fedora 等）。
• 已安装 curl 或 wget（用于下载安装脚本）。
• 已安装 git（NVM 安装脚本会通过 Git 克隆仓库，部分系统可能预装）。

2.2 清理现有 Node.js（可选但推荐）#

如果系统中已通过 apt、yum 等包管理器安装了 Node.js，建议先卸载，避免与 NVM 管理的版本冲突：

# Ubuntu/Debian
sudo apt remove nodejs npm
 
# CentOS/RHEL
sudo yum remove nodejs npm
 
# Fedora
sudo dnf remove nodejs npm

如果仅需保留系统 Node.js（不推荐），需注意 NVM 管理的版本优先级更高，可能覆盖系统版本。

2.3 检查依赖工具#

确保 curl、wget 和 git 已安装：

# 检查 curl
curl --version
 
# 检查 wget
wget --version
 
# 检查 git
git --version

若某工具缺失，通过包管理器安装：

# Ubuntu/Debian
sudo apt install curl wget git
 
# CentOS/RHEL
sudo yum install curl wget git
 
# Fedora
sudo dnf install curl wget git

3. NVM 安装步骤#

NVM 官方推荐通过 GitHub 仓库的安装脚本进行安装，步骤如下：

3.1 检查是否已安装 NVM#

安装前先检查是否存在旧版本 NVM，避免冲突：

nvm --version

若输出 nvm: command not found，则表示未安装，可继续；若输出版本号，建议先卸载旧版本（见 故障排除）。

3.2 下载并运行安装脚本#

NVM 的最新版本可在 GitHub 发布页 查看。截至本文发布，最新稳定版为 v0.39.7，安装命令如下：

方式一：使用 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

安全提示：运行未知脚本前，建议先查看脚本内容：

# 下载脚本到本地
curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh
# 查看脚本内容
cat install_nvm.sh
# 确认安全后再运行
bash install_nvm.sh

3.3 配置 Shell 环境#

安装脚本会自动将 NVM 配置添加到用户的 Shell 配置文件（如 ~/.bashrc、~/.zshrc、~/.profile 或 ~/.bash_profile），但需手动刷新 Shell 环境使其生效。

步骤 1：确认配置文件已更新#

打开 Shell 配置文件（以 ~/.bashrc 为例）：

vim ~/.bashrc  # 或使用 nano、code 等编辑器

检查文件末尾是否有类似以下内容（NVM 自动添加）：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # 加载 NVM
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # 加载 NVM bash 补全

若未添加，需手动复制上述内容到配置文件并保存。

步骤 2：刷新 Shell 环境#

执行以下命令使配置生效，或直接重启终端：

# bash 用户
source ~/.bashrc
 
# zsh 用户
source ~/.zshrc
 
# 其他 Shell（如 fish）
source ~/.config/fish/config.fish  # 根据实际配置文件路径调整

4. 验证 NVM 安装#

安装完成后，运行以下命令验证 NVM 是否可用：

nvm --version

若输出类似 0.39.7 的版本号，说明安装成功。

若提示 nvm: command not found，可能原因：

• Shell 配置文件未正确更新（见 3.3 步骤 1）。
• 未刷新 Shell 环境（见 3.3 步骤 2）。

5. NVM 常用命令详解#

NVM 的核心功能通过命令行实现，以下是最常用的命令：

5.1 查看 NVM 版本#

nvm --version  # 如：0.39.7

5.2 安装 Node.js#

安装指定版本#

nvm install <version>  # 如安装 v20.10.0
nvm install 20.10.0

安装 LTS 版本（推荐生产环境）#

LTS（Long Term Support）版本为长期支持版，稳定性更高：

nvm install --lts  # 安装最新 LTS 版本
nvm install lts/hydrogen  # 安装指定代号的 LTS（如 hydrogen 对应 Node.js 18）

安装最新稳定版#

nvm install node  # 安装最新稳定版 Node.js

5.3 查看已安装 Node.js 版本#

nvm ls  # 列出所有已安装版本，当前使用版本标为 `->`
nvm ls-remote  # 列出远程可用版本（可加 --lts 过滤 LTS 版本）

示例输出：

->     v20.10.0
       v21.2.0
default -> 20 (-> v20.10.0)
iojs -> N/A (default)
unstable -> N/A (default)
lts/* -> lts/hydrogen (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
...

5.4 切换 Node.js 版本#

临时切换（当前 Shell 生效）#

nvm use <version>  # 如切换到 v18.18.0
nvm use 18.18.0

设置默认版本（全局生效）#

nvm alias default <version>  # 如设置 v20.10.0 为默认版本
nvm alias default 20.10.0

取消默认版本#

nvm unalias default

5.5 卸载 Node.js 版本#

nvm uninstall <version>  # 如卸载 v16.20.2
nvm uninstall 16.20.2

5.6 查看当前使用的 Node.js 版本#

nvm current  # 如输出 v20.10.0
node -v  # 等效于直接查看 Node.js 版本

6. NVM 常见使用场景#

6.1 为项目指定 Node.js 版本（.nvmrc 文件）#

在项目根目录创建 .nvmrc 文件，写入目标 Node.js 版本，可实现进入项目目录时自动切换版本：

1. 创建 .nvmrc：

   echo "20.10.0" > .nvmrc  # 或指定 LTS 代号：echo "lts/hydrogen" > .nvmrc

2. 进入项目目录后运行：

   nvm use  # 自动读取 .nvmrc 并切换版本（若未安装，会提示安装）

提示：配合 Shell 插件（如 direnv）可实现进入目录时自动执行 nvm use，无需手动操作。

6.2 安装项目依赖的 Node.js 版本#

若项目已包含 .nvmrc，可直接安装文件中指定的版本：

nvm install  # 自动读取 .nvmrc 并安装对应版本

6.3 在不同项目间快速切换版本#

例如：

• 项目 A 依赖 Node.js 18，项目 B 依赖 Node.js 20。
• 进入项目 A 目录：nvm use 18。
• 进入项目 B 目录：nvm use 20。

7. NVM 最佳实践#

7.1 优先使用 LTS 版本#

生产环境强烈推荐使用 LTS 版本，避免因非 LTS 版本停止维护导致安全风险。可通过 nvm install --lts 安装最新 LTS。

7.2 为项目添加 .nvmrc 文件#

团队协作时，.nvmrc 可统一项目的 Node.js 版本，避免因版本差异导致的兼容性问题。提交 .nvmrc 到 Git 仓库，并在 README 中说明使用 nvm use 切换版本。

7.3 定期更新 NVM#

NVM 本身也在迭代，定期更新可获取新功能和 bug 修复：

nvm upgrade  # 更新 NVM 到最新版本

7.4 清理无用 Node.js 版本#

长期使用后，可卸载不再需要的 Node.js 版本，释放磁盘空间：

nvm uninstall <version>  # 卸载指定版本

7.5 避免使用 sudo 安装全局包#

NVM 管理的 Node.js 版本中，全局包安装路径位于用户目录（~/.nvm/versions/node/<version>/lib/node_modules），无需 sudo：

npm install -g npm  # 升级 npm（无需 sudo）
npm install -g yarn  # 安装 yarn（无需 sudo）

7.6 设置默认 Node.js 版本#

避免每次打开终端都需手动切换版本，通过 nvm alias default <version> 设置默认版本，确保终端启动时自动加载。

8. 常见问题与故障排除#

8.1 nvm: command not found#

原因：Shell 未加载 NVM 配置。
解决：

1. 检查 Shell 配置文件（如 ~/.bashrc）是否包含 NVM 配置（见 3.3 步骤 1）。
2. 手动刷新配置：source ~/.bashrc（或对应 Shell 的配置文件）。

8.2 安装 Node.js 时卡在 "Downloading" 或失败#

原因：网络问题或依赖缺失（如编译工具）。
解决：

• 网络问题：尝试切换网络或使用代理。
• 依赖缺失：安装编译工具（以 Ubuntu 为例）：

  sudo apt install build-essential libssl-dev  # 用于编译 Node.js 源码依赖

8.3 切换版本后 npm 命令失效#

原因：Node.js 版本未正确安装，或 npm 包损坏。
解决：

1. 重新安装对应 Node.js 版本：nvm reinstall-packages <version>。
2. 清除 npm 缓存：npm cache clean --force。

8.4 卸载 NVM#

如需完全卸载 NVM，执行以下步骤：

1. 删除 NVM 目录：rm -rf "$NVM_DIR"。
2. 删除 Shell 配置文件（如 ~/.bashrc）中 NVM 相关的配置行（见 3.3 步骤 1）。
3. 刷新 Shell 环境：source ~/.bashrc。

9. 总结#

NVM 是 Node.js 开发者的必备工具，通过它可以轻松管理多个 Node.js 版本，解决版本冲突和权限问题。本文从安装、验证、常用命令到最佳实践，详细介绍了 NVM 在 Linux 下的使用方法。

核心要点：

• 通过官方脚本安装 NVM，确保配置文件正确加载。
• 使用 nvm install、nvm use、nvm alias 管理版本。
• 配合 .nvmrc 文件实现项目版本统一。
• 遵循最佳实践（如优先 LTS 版本、定期更新 NVM），提升开发效率。

10. 参考资料#

• NVM 官方 GitHub 仓库
• NVM 官方文档
• Node.js 官方网站
• Node.js LTS 版本列表
• nvm-windows（Windows 替代品）