Node.js 版本管理工具 nvm 完全指南 - 从入门到精通

2026-01-23 · 7 min read · node

在 Node.js 开发中，不同项目可能需要不同版本的 Node.js 环境。如何轻松地在多个 Node.js 版本之间切换？nvm（Node Version Manager） 是最流行的解决方案之一。它允许你在同一台机器上安装和切换多个 Node.js 版本，为每个项目配置独立的运行环境。本文将系统性地介绍 nvm 的安装、配置、常用命令以及实战技巧。

简介

什么是 nvm

nvm（Node Version Manager） 是一个用于管理多个 Node.js 版本的命令行工具。它允许你：

在同一台机器上安装多个 Node.js 版本
在不同版本之间快速切换
为每个项目设置特定的 Node.js 版本
方便地升级或降级 Node.js 版本

为什么需要 nvm

场景	问题	nvm 的作用
多项目并行开发	项目 A 需要 Node 16，项目 B 需要 Node 18	快速切换不同版本
依赖兼容性问题	新版 Node.js 与某些包不兼容	降级到稳定版本
测试兼容性	需要测试代码在不同 Node 版本下的表现	方便地在多个版本间测试
团队协作	团队成员使用不同 Node 版本导致环境差异	统一项目指定的 Node 版本

nvm 的版本

nvm 有两个主要版本，针对不同操作系统：

 1nvm
 2├── nvm（Node Version Manager）
 3│   ├── 适用于 macOS 和 Linux
 4│   ├── 使用 bash 脚本
 5│   └── 功能更完整
 6│
 7└── nvm-windows
 8    ├── 适用于 Windows
 9    ├── 使用 Go 编写
10    └── 命令语法略有不同

安装 nvm

macOS / Linux 安装

使用 curl 安装

1# 下载并执行安装脚本
2curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

使用 wget 安装

1# 下载并执行安装脚本
2wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装后的配置

安装完成后，需要重新加载 shell 配置：

1# 重新加载配置
2source ~/.bashrc
3
4# 或使用 zsh
5source ~/.zshrc

验证安装

1# 检查 nvm 是否安装成功
2nvm --version
3
4# 输出示例：0.39.7

如果命令未找到，请确保你的 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）中包含了 nvm 的加载语句。安装脚本通常会自动添加以下内容：

1export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
2[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Windows 安装

对于 Windows 用户，需要使用 nvm-windows（与 Unix 版本的 nvm 不同）。

下载安装包

访问 nvm-windows Releases 页面，下载最新的 nvm-setup.exe 安装包。

安装步骤

运行 nvm-setup.exe
选择 nvm 的安装路径（默认：C:\Users\<用户名>\AppData\Roaming\nvm）
选择 Node.js 的安装路径（默认：C:\Program Files\nodejs）
完成安装

验证安装

1# 在新的命令行窗口中检查
2nvm version
3
4# 输出示例：1.1.12

通过 Homebrew 安装（macOS）

 1# 安装 nvm
 2brew install nvm
 3
 4# 创建 nvm 目录（如果不存在）
 5mkdir ~/.nvm
 6
 7# 添加到 shell 配置（根据你的 shell 选择）
 8
 9# 对于 zsh（macOS 默认）
10echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
11echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && . "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrc
12
13# 重新加载配置
14source ~/.zshrc

基础用法

查看 nvm 版本

1nvm --version

查看已安装的 Node 版本

 1# 列出所有已安装的版本
 2nvm ls
 3
 4# 输出示例：
 5#        v14.21.3
 6# ->     v16.20.2
 7#        v18.19.0
 8#        v20.11.1
 9# default -> v18.19.0
10# iojs -> N/A (default)

-> 表示当前激活的版本，default 表示默认使用的版本。

查看可用的 Node 版本

1# 查看所有可用的远程版本
2nvm ls-remote
3
4# 查看特定版本
5nvm ls-remote v18
6nvm ls-remote v18.19.0
7
8# 查看最新的 LTS 版本
9nvm ls-remote --lts

LTS（Long Term Support）是长期支持版本，更加稳定适合生产环境使用。nvm 在列出远程版本时会标记 LTS 版本，例如 v20.11.1 (Latest LTS: Iron)。

安装 Node 版本

 1# 安装最新版本
 2nvm install node
 3
 4# 安装指定版本
 5nvm install 18.19.0
 6nvm install v18.19.0  # 带前缀也可以
 7
 8# 安装最新的 LTS 版本
 9nvm install --lts
10nvm install --lts=Iron  # 安装特定的 LTS 版本
11
12# 安装多个版本
13nvm install 16.20.2
14nvm install 18.19.0
15nvm install 20.11.1

切换 Node 版本

1# 切换到已安装的版本
2nvm use 18.19.0
3
4# 切换到最新 LTS 版本
5nvm use --lts
6
7# 使用主版本号（选择该主版本下的最新安装版本）
8nvm use 18

设置默认版本

1# 设置默认版本（每次打开终端自动使用）
2nvm alias default 18.19.0
3
4# 设置为当前版本
5nvm alias default node
6
7# 查看默认版本
8nvm alias default

卸载 Node 版本

1# 卸载指定版本
2nvm uninstall 16.20.2
3
4# 卸载多个版本
5nvm uninstall 14.21.3 16.20.2

高级用法

版本别名

nvm 允许为 Node 版本创建别名，方便管理。

 1# 创建别名
 2nvm alias prod 18.19.0
 3nvm alias dev 20.11.1
 4
 5# 使用别名切换
 6nvm use prod
 7nvm use dev
 8
 9# 查看所有别名
10nvm alias
11
12# 删除别名
13nvm unalias prod

自动切换版本

通过项目的 .nvmrc 文件，nvm 可以自动切换到项目指定的 Node 版本。

创建 .nvmrc 文件

1# 在项目根目录创建 .nvmrc 文件
2echo "18.19.0" > .nvmrc

自动切换配置

在你的 shell 配置文件（~/.bashrc 或 ~/.zshrc）中添加以下内容：

 1# 自动加载 .nvmrc 文件中指定的 Node 版本
 2autoload -U add-zsh-hook
 3load-nvmrc() {
 4  local node_version="$(nvm version)"
 5  local nvmrc_path="$(nvm_find_nvmrc)"
 6
 7  if [ -n "$nvmrc_path" ]; then
 8    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
 9
10    if [ "$nvmrc_node_version" = "N/A" ]; then
11      nvm install
12    elif [ "$nvmrc_node_version" != "$node_version" ]; then
13      nvm use
14    fi
15  elif [ "$node_version" != "$(nvm version default)" ]; then
16    echo "Reverting to nvm default version"
17    nvm use default
18  fi
19}
20
21add-zsh-hook chpwd load-nvmrc
22load-nvmrc

手动切换到 .nvmrc 指定的版本

1# 进入项目目录后手动切换
2cd /path/to/project
3nvm use
4
5# 找到 .nvmrc 文件并自动切换
6# 输出：Found '/path/to/project/.nvmrc' with version <18.19.0>
7# 输出：Now using node v18.19.0 (npm v9.2.0)

同时安装 io.js

nvm 也支持安装和切换 io.js（Node.js 的分支，已合并回 Node.js）：

1# 安装 io.js
2nvm install iojs
3
4# 列出 io.js 版本
5nvm ls-remote iojs
6
7# 切换到 io.js
8nvm use iojs

Windows 版本（nvm-windows）

nvm-windows 命令差异

nvm-windows 的命令语法与 Unix 版本略有不同：

操作	Unix 版本（nvm）	Windows 版本（nvm-windows）
列出已安装版本	`nvm ls`	`nvm list` 或 `nvm ls`
列出远程版本	`nvm ls-remote`	`nvm list available`
安装版本	`nvm install 18.19.0`	`nvm install 18.19.0`
使用版本	`nvm use 18.19.0`	`nvm use 18.19.0`
设置默认	`nvm alias default`	自动记录最后一次使用的版本
卸载版本	`nvm uninstall`	`nvm uninstall`

Windows 常用命令

 1# 列出可用的 Node 版本
 2nvm list available
 3
 4# 安装指定版本
 5nvm install 18.19.0
 6
 7# 切换版本
 8nvm use 18.19.0
 9
10# 查看当前使用的版本
11nvm current
12
13# 卸载版本
14nvm uninstall 18.19.0

常见问题排查

nvm 命令找不到

问题： 安装后运行 nvm 命令提示 "command not found"

解决方案：

确认 nvm 已安装
检查 shell 配置文件是否包含 nvm 加载语句
重新加载 shell 配置或重启终端

1# 检查 nvm 安装目录
2ls ~/.nvm
3
4# 手动加载 nvm
5source ~/.nvm/nvm.sh

Node 版本切换不生效

问题： 运行 nvm use 后，node -v 仍然显示旧版本

解决方案：

检查是否有其他 Node 安装（如通过 Homebrew 或官方安装包）
确保 PATH 中 nvm 的 Node 路径优先

1# 检查 node 的实际路径
2which node
3
4# 输出应该是：/Users/username/.nvm/versions/node/v18.19.0/bin/node
5# 如果不是，说明使用了其他安装的 Node

npm 的问题

nvm 会为每个 Node 版本安装对应的 npm。

1# 查看当前 npm 版本
2npm -v
3
4# 为当前 Node 版本安装特定 npm 版本
5npm install -g npm@9.2.0
6
7# 不同 Node 版本可以有不同的 npm 版本

权限问题

问题： 全局安装包时出现权限错误

解决方案：

1# 配置 npm 全局安装路径到用户目录
2npm config set prefix "$HOME/.npm-global"
3
4# 将路径添加到 PATH
5echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
6source ~/.bashrc

卸载 nvm

如果需要完全卸载 nvm：

1# 删除 nvm 目录
2rm -rf ~/.nvm
3
4# 从 shell 配置文件中删除 nvm 配置
5# 编辑 ~/.bashrc 或 ~/.zshrc，删除 nvm 相关的行

项目实战

场景1：维护多个不同版本的项目

假设你有以下项目：

项目 A（生产环境）：使用 Node 16 LTS
项目 B（新开发）：使用 Node 18 LTS
项目 C（实验性）：使用 Node 20

 1# 安装所需版本
 2nvm install 16.20.2
 3nvm install 18.19.0
 4nvm install 20.11.1
 5
 6# 为每个项目创建 .nvmrc 文件
 7cd /path/to/project-a
 8echo "16.20.2" > .nvmrc
 9
10cd /path/to/project-b
11echo "18.19.0" > .nvmrc
12
13cd /path/to/project-c
14echo "20.11.1" > .nvmrc
15
16# 进入项目自动切换
17cd /path/to/project-a
18nvm use  # 自动切换到 Node 16.20.2

场景2：团队协作统一 Node 版本

在项目中添加 .nvmrc 文件，确保所有开发者使用相同的 Node 版本。

1# .nvmrc 文件内容
218.19.0

团队中的其他成员进入项目后，只需要运行：

1# 进入项目目录
2cd /path/to/project
3
4# 自动切换版本（如果配置了自动切换）
5nvm use
6
7# 或者手动安装指定版本（如果本地未安装）
8nvm install

可以在 package.json 中添加脚本检查 Node 版本：

1{
2  "scripts": {
3    "preinstall": "nvm install || true",
4    "start": "node -e \"console.log('Node version:', process.version)\""
5  }
6}

场景3：测试代码的跨版本兼容性

使用 nvm 在多个 Node 版本下运行测试：

 1# 创建测试脚本 test-all-versions.sh
 2#!/bin/bash
 3
 4versions=("16.20.2" "18.19.0" "20.11.1")
 5
 6for version in "${versions[@]}"; do
 7  echo "Testing with Node $version"
 8  nvm use $version
 9  npm test
10  if [ $? -ne 0 ]; then
11    echo "Tests failed on Node $version"
12    exit 1
13  fi
14done
15
16echo "All tests passed!"

最佳实践

1. 使用 LTS 版本作为默认

1# 安装最新的 LTS 版本
2nvm install --lts
3
4# 设置为默认版本
5nvm alias default 'lts/*'

2. 为每个项目使用 .nvmrc

确保项目的一致性和可移植性：

1# 在项目根目录创建 .nvmrc
2echo "$(node -v)" > .nvmrc
3
4# 提交到版本控制
5git add .nvmrc
6git commit -m "Add .nvmrc for Node version specification"

3. 定期更新 nvm

1# 更新 nvm 到最新版本
2cd ~/.nvm
3git fetch origin
4git checkout $(git describe --abbrev=0 --tags)
5source ~/.nvm/nvm.sh

4. 保持 Node 版本合理

不要安装过多版本，只保留实际需要的：

1# 查看已安装版本
2nvm ls
3
4# 卸载不再使用的版本
5nvm uninstall <old-version>

5. 配置 npm 全局包

为每个 Node 版本单独配置全局包，避免版本冲突：

 1# 切换到特定版本
 2nvm use 18.19.0
 3
 4# 安装全局包
 5npm install -g pnpm yarn
 6
 7# 切换到另一个版本
 8nvm use 20.11.1
 9
10# 重新安装全局包
11npm install -g pnpm yarn

常用命令速查表

命令	说明
`nvm --version`	查看 nvm 版本
`nvm ls`	列出已安装的 Node 版本
`nvm ls-remote`	列出所有可用的远程版本
`nvm install <version>`	安装指定版本
`nvm install --lts`	安装最新的 LTS 版本
`nvm uninstall <version>`	卸载指定版本
`nvm use <version>`	切换到指定版本
`nvm alias default <version>`	设置默认版本
`nvm current`	显示当前使用的版本
`nvm which <version>`	显示指定版本的安装路径

总结

nvm 是 Node.js 开发者必备的工具之一，它简化了多版本管理的复杂性，让开发者能够轻松应对不同项目的需求。

核心要点：

nvm 允许在同一台机器上安装和管理多个 Node.js 版本
通过 .nvmrc 文件可以为项目指定 Node 版本，确保环境一致性
LTS 版本更适合生产环境使用
Windows 用户需要使用 nvm-windows，命令语法略有差异
定期清理不需要的版本，保持环境整洁

实践建议：

为每个项目创建 .nvmrc 文件
使用 LTS 版本作为默认环境
定期更新 nvm 到最新版本
合理规划 Node 版本，避免安装过多无用版本
配置自动切换脚本，提升开发效率

掌握 nvm 的使用，将极大提升 Node.js 开发体验，让你在不同项目间无缝切换，专注于代码本身而不是环境配置。

Node.js 版本管理工具 nvm 完全指南 - 从入门到精通

简介

什么是 nvm

为什么需要 nvm

nvm 的版本

安装 nvm

macOS / Linux 安装

使用 curl 安装

使用 wget 安装

安装后的配置

验证安装

Windows 安装

下载安装包

安装步骤

验证安装

通过 Homebrew 安装（macOS）

基础用法

查看 nvm 版本

查看已安装的 Node 版本

查看可用的 Node 版本

安装 Node 版本

切换 Node 版本

设置默认版本

卸载 Node 版本

高级用法

版本别名

自动切换版本

创建 .nvmrc 文件

自动切换配置

手动切换到 .nvmrc 指定的版本

同时安装 io.js

Windows 版本（nvm-windows）

nvm-windows 命令差异

Windows 常用命令

常见问题排查

nvm 命令找不到

Node 版本切换不生效

npm 的问题

权限问题

卸载 nvm

项目实战

场景1：维护多个不同版本的项目

场景2：团队协作统一 Node 版本

场景3：测试代码的跨版本兼容性

最佳实践

1. 使用 LTS 版本作为默认

2. 为每个项目使用 .nvmrc

3. 定期更新 nvm

4. 保持 Node 版本合理

5. 配置 npm 全局包

常用命令速查表

总结

参考资源