nvm 安装与 Node.js 版本管理指南

nvm 是 Node Version Manager 的缩写，用来在同一台电脑上安装和切换多个 Node.js 版本。它按用户和 Shell 管理 Node.js，默认把文件放在 ~/.nvm，适合开发环境、课程项目和需要不同 Node.js 版本的多个仓库。

本文使用 nvm 官方安装脚本，覆盖常见的 macOS、Linux 和类 Unix Shell 环境。安装完成后，可以用一套命令完成 Node.js LTS、默认版本、项目版本和全局命令的管理。

安装前确认 Shell

先确认当前终端使用的 Shell：

printf '%s\n' "$SHELL"

常见结果包括 /bin/zsh 和 /bin/bash。安装脚本会根据当前环境尝试找到 Shell 配置文件，并将 nvm 的加载代码写入其中。常见配置文件如下：

使用自定义 Shell 配置目录时，以当前环境实际读取的文件为准。可以先运行下面的命令确认配置变量：

printf '%s\n' "${ZDOTDIR:-$HOME}"

使用官方脚本安装 nvm

curl 安装方式

在终端执行：

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

安装脚本会完成以下工作：

• 创建默认目录 ~/.nvm。
• 下载 nvm 脚本和补全文件。
• 尝试把 NVM_DIR 和 nvm 加载代码写入当前用户的 Shell 配置文件。
• 保留当前用户权限，后续安装 Node.js 可以直接使用当前账号。

wget 安装方式

系统中没有 curl 时，可以使用 wget：

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

安装脚本的版本号会随 nvm 发布更新。使用新版本前，可以先查看 nvm 官方仓库 中的最新安装说明，再替换命令里的版本号。

重新加载 Shell 配置

安装完成后，重新打开一个终端窗口，或根据实际 Shell 重新加载配置：

# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc

系统使用 ~/.bash_profile 作为 Bash 配置文件时，执行：

source ~/.bash_profile

每次只加载当前实际使用的配置文件即可。安装脚本已经写入配置时，保持一份 nvm 加载代码可以让环境更容易维护。

验证 nvm 是否安装成功

使用 command -v 检查 nvm。nvm 通过 Shell 函数提供命令入口，这个检查方式比查找普通可执行文件更准确：

command -v nvm
nvm --version

正常结果会类似下面这样：

nvm
0.40.8

command -v nvm 没有输出时，检查当前 Shell 是否加载了配置文件：

printf '%s\n' "${NVM_DIR:-未设置}"
ls -la "${NVM_DIR:-$HOME/.nvm}"

也可以将以下配置放入当前 Shell 的配置文件，再重新打开终端：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

这段配置适用于 Zsh 和 Bash。nvm.sh 提供 nvm 命令，bash_completion 提供补全功能。

安装 Node.js LTS

验证 nvm 后，安装长期支持版 Node.js：

nvm install --lts
nvm use --lts

安装完成后检查 Node.js 和 npm：

node --version
npm --version
nvm current

nvm install --lts 会安装当前可用的 LTS 版本，并在当前 Shell 中选中它。LTS 适合需要长期维护的项目和日常开发环境。

设置默认 Node.js 版本

设置默认别名后，新 Shell 会优先使用这个版本：

nvm alias default 'lts/*'
nvm use default

确认默认版本和 nvm 实际管理的 Node.js 路径：

nvm alias default
nvm current
command -v node

command -v node 应该指向 ~/.nvm/versions/node/ 下的路径。每个 Node.js 版本都有自己的目录和全局 npm 包空间。

也可以把某个主版本设为默认版本：

nvm install 20
nvm alias default 20
nvm use default

这里的 20 表示 Node.js 20 系列中可用的最新版本。项目对具体补丁版本有要求时，可以直接指定完整版本号，例如 nvm install 20.19.0。

安装和切换多个 Node.js 版本

查看可安装的 LTS 版本：

nvm ls-remote --lts

安装并切换到 Node.js 18：

nvm install 18
nvm use 18

切换回 Node.js 20：

nvm use 20

查看本机版本、别名和当前版本：

nvm ls
nvm current

常用操作可以记成下面这组命令：

删除前先确认当前版本和已安装版本：

nvm current
nvm ls

当前正在使用的版本需要先切换到其他版本，再执行卸载。

使用 .nvmrc 固定项目版本

.nvmrc 是放在项目根目录中的纯文本文件，用来声明项目使用的 Node.js 版本。进入项目目录后创建文件：

cd path/to/project
printf '%s\n' '20' > .nvmrc
nvm install
nvm use

nvm install 和 nvm use 会读取当前目录或上级目录中的 .nvmrc。文件内容可以使用主版本号、完整版本号或 LTS 别名：

20

团队项目通常将 .nvmrc 一起提交到 Git，这样每位成员都能快速获得一致的 Node.js 主版本。更换项目版本时，同时更新 .nvmrc、项目文档和 CI 配置。

检查项目当前使用的版本：

nvm current
node --version

自动切换可以通过 Shell 插件实现，也可以保留手动执行 nvm use 的方式。手动切换的行为更容易观察，适合先建立稳定的项目流程。

nvm 与 npm、pnpm 的关系

三者职责不同：

nvm 管理 Node.js 版本，npm 和 pnpm 管理项目依赖。切换 Node.js 版本后，全局 npm 包也会切换到对应版本的目录，因此每个 Node.js 版本都需要单独安装需要的全局工具。

在当前 Node.js 版本下安装 pnpm：

nvm use --lts
npm install --global pnpm
pnpm --version

项目依赖建议写入项目的 package.json，并通过项目脚本调用。全局安装适合提供命令行入口的工具，例如 pnpm、Astro CLI 或其他开发辅助工具。

常见问题

nvm: command not found

依次检查默认目录、加载脚本和当前 Shell：

printf '%s\n' "${NVM_DIR:-$HOME/.nvm}"
test -s "${NVM_DIR:-$HOME/.nvm}/nvm.sh" && printf '%s\n' 'nvm.sh 存在'
printf '%s\n' "$SHELL"

确认文件存在后，重新加载对应配置文件：

source ~/.zshrc
# 或
source ~/.bashrc

仍然无法加载时，重新运行官方安装脚本，并观察安装结束时给出的配置文件提示。

node 仍然来自系统路径

执行下面的命令查看当前状态：

nvm current
command -v node

切换到 nvm 版本：

nvm use --lts
command -v node

终端缓存了旧路径时，重新打开终端窗口，再次执行检查命令。

切换版本后找不到全局命令

全局包按 Node.js 版本分别保存。切换版本后，使用当前版本重新安装命令：

nvm use 20
npm install --global pnpm

项目内的依赖由 package.json 和锁文件管理，进入项目后使用项目包管理器安装即可。

安装脚本下载失败

先检查网络和工具：

curl --version
wget --version

具备 wget 时可以改用 wget 安装命令。公司网络、代理或证书策略可能影响 GitHub Raw 地址的访问，处理网络策略后重新执行官方脚本。

Windows 原生终端的使用范围

nvm-sh 面向 POSIX Shell。Windows 用户可以在 WSL 中按本文安装，也可以使用独立的 nvm-windows 项目，两者的安装方式和部分命令存在差异。

更新和卸载 nvm

查看当前 nvm 版本：

nvm --version

升级 nvm 前，先阅读官方仓库的发布说明，再使用对应版本的安装脚本。安装脚本会更新 ~/.nvm 中的 nvm 文件，同时保留已经安装的 Node.js 版本。

如果需要移除 nvm，先删除 Shell 配置文件中的 nvm 加载代码，再移除默认目录：

rm -rf "${NVM_DIR:-$HOME/.nvm}"

这个操作会删除 nvm 管理的全部 Node.js 版本和全局包。需要保留环境时，先执行 nvm ls，记录项目版本和全局工具清单。

一次完成安装的命令清单

首次安装可以按下面顺序执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
source ~/.zshrc
nvm --version
nvm install --lts
nvm alias default 'lts/*'
nvm use default
node --version
npm --version

当前 Shell 使用 Bash 时，将 source ~/.zshrc 替换为实际的 Bash 配置文件。完成这组命令后，nvm、Node.js LTS 和默认版本就已经建立；进入具体项目时，再根据 .nvmrc 执行 nvm install 和 nvm use。