---
url: https://eoht.net/notes/nvm.md
description: 按 nvm 官方方式安装并初始化 shell，使用 LTS 和项目 .nvmrc 管理 Node.js，检查实际版本，并迁移全局 npm 软件包。
---

# nvm 安装与 Node.js 版本管理 {#manage-node-versions-with-nvm}

本文使用 [nvm-sh/nvm](https://github.com/nvm-sh/nvm)，适用于 macOS、Linux 和 WSL 的 Bash / zsh 等受支持 shell。原生 Windows 的 nvm-windows 是另一个项目；fish 也不能直接加载本文的 nvm 脚本。

## nvm 与 n 的区别 {#nvm-vs-n}

nvm 按用户安装，并在每个 shell 会话中加载，通过调整当前会话 PATH 选择 Node.js。`n` 使用另一套安装和切换机制，不应同时混用多个版本管理器。全局 npm 包的实际位置取决于当前 Node 安装和 npm prefix，不能统一假定为 `/usr/local/lib/node_modules`。

## 检查已有的全局 Node/npm {#remove-globally-installed-node-and-npm}

安装 nvm 前先确认现有命令来源：

```bash
command -v node
command -v npm
node --version
npm prefix -g
```

未安装时出现“command not found”即可。系统 Node 不一定要先卸载；若决定移除，应按原安装渠道操作，并确认没有其他工具依赖它。例如只有确认为 Homebrew 安装时，才考虑 `brew uninstall node`。

不要批量删除 `/usr/local`、`/opt/local` 下所有带 node 的文件，也不必为安装 nvm 清空 npm 缓存。已有 `~/.npmrc` 若设置了自定义 `prefix`，需按 nvm 的兼容性说明处理，否则可能把全局包装到错误目录。

## 安装 nvm {#install-nvm}

截至 2026-10-24，官方 README 使用 `v0.40.8`。下载固定版本脚本，阅读后再运行：

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

安装器会尝试在 shell 启动文件中添加初始化内容。重新打开终端；若当前会话仍找不到 nvm，可按实际安装目录加载（下例适用于官方默认目录规则）：

```bash
export NVM_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/nvm"
if [ -z "${XDG_CONFIG_HOME-}" ]; then
  export NVM_DIR="$HOME/.nvm"
fi
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
command -v nvm
nvm --version
```

`command -v nvm` 应输出 `nvm`。它是 shell 函数，不能用 `which nvm` 是否找到二进制来判断安装成功。若要持久生效，确认上述初始化已在当前 shell 的启动文件中，例如 zsh 的 `~/.zshrc`，不要重复添加。

Homebrew 安装方式不受 nvm 上游支持；遇到该渠道的安装问题，应先按上游说明迁移，再排查版本切换。

## 安装多个 Node/npm 版本 {#install-multiple-node-versions}

新项目可先查看可用 LTS，并安装当前 LTS：

```bash
nvm ls-remote --lts
nvm install --lts
node --version
npm --version
```

项目要求特定版本时，以项目声明为准，例如 `nvm install 22` 安装该主版本下可用的版本，`nvm install 24` 安装另一主版本。选择版本前同时核对项目兼容性与 [Node.js 支持周期](https://nodejs.org/en/about/previous-releases)。

## 在不同版本间切换 {#switch-node-versions}

```bash
nvm use 22
node --version
nvm use 24
node --version
```

上述两个版本需要先安装。使用已安装的最新 LTS 可执行 `nvm use --lts`；希望新终端默认使用某个已安装版本时，可设置 `nvm alias default 24`。`nvm use node` 的 `node` 是版本别名，不等于“当前 LTS”。

## 列出已安装实例 {#list-installed-node-versions}

```bash
nvm ls
nvm current
```

列表可以查看已安装版本和别名，`current` 显示当前会话使用的版本。

## 在项目中使用不同版本的 Node {#use-project-specific-node-version}

项目已有 `.nvmrc` 时，在项目目录执行：

```bash
nvm install
nvm use
node --version
```

nvm 会读取 `.nvmrc`。项目尚未锁定版本时，可在确认当前版本就是所需版本后记录它：

```bash
node --version > .nvmrc
```

这会覆盖现有文件，因此不要在已有 `.nvmrc` 的项目中盲目执行。固定完整版本有助于复现；仅安装 nvm 不会自动在每次 `cd` 时切换版本，自动切换需要额外的 shell 集成。

## 在多环境中使用 npm {#use-npm-across-environments}

各 Node 版本通常带有各自的 npm，全局包默认位于该 nvm 版本目录；可用 `npm prefix -g` 查看当前路径。nvm 的用户目录安装不需要 `sudo npm install -g`。

若已安装 Node 22，准备安装 Node 24 并迁移其全局包，可执行：

```bash
nvm install 24 --reinstall-packages-from=22
npm ls -g --depth=0
```

迁移全局包不等于迁移项目依赖，也不保证旧包兼容新 Node。项目依赖仍应按项目使用的包管理器和锁文件安装，并运行项目自己的验证。

参考：[nvm 安装与更新](https://github.com/nvm-sh/nvm#installing-and-updating)、[nvm 使用说明](https://github.com/nvm-sh/nvm#usage)。