怎么使用nvm在Windows和Mac上管理多个Node.js版本

一、认识两个系统上的 NVM：底层机制的区别

在开始安装之前，必须明确一个关键事实：macOS 上的 nvm 与 Windows 上的 nvm-windows 是由不同作者维护的两个独立开源项目，二者在底层运作机制上有根本区别。

在 macOS 及 Linux 平台上，我们使用的是由社区维护的 nvm-sh/nvm。它本质上是一个由 Shell 编写的内联函数库。每次在终端执行版本切换时，它仅通过临时改变当前 Shell 会话的 PATH 环境变量，使其优先指向目标 Node 版本的可执行文件目录。这种机制决定了它的切换是“窗口级局部隔离”的，两个终端窗口完全可以同时运行不同的 Node 版本，且无需任何系统管理员提权操作。

而在 Windows 平台上，由于控制台环境与系统机制的特殊性，直接运行 POSIX Shell 脚本并不现实。开发者通常使用的是由 Corey Butler 开发的 nvm-windows。它是一个使用 Go 语言编译的原生可执行程序（nvm.exe）。它的版本切换机制是通过在系统目录中创建或更新一个 NTFS 符号链接（Symlink Junction）（默认是 C:\Program Files\nodejs），让这个固定路径动态指向被选中的具体版本目录。因此在 Windows 上，一旦切换版本，就是全系统全局生效的。

为了让后续操作更加清晰，下表整理了两个平台核心特性的主要对照：

对比维度	macOS (nvm-sh)	Windows (nvm-windows)
底层类型	POSIX Shell 函数脚本	Go 编写的原生二进制可执行程序
切换机制	动态重定向当前终端 PATH 环境变量	动态修改全局符号链接（Symlink Junction）
切换作用域	终端会话隔离（不同窗口可使用不同版本）	全系统全局生效（所有窗口同步变更）
安装权限	纯用户权限即可（默认安装于 ~/.nvm）	需管理员权限或开启 Windows「开发者模式」
远程查询命令	nvm ls-remote	nvm list available

二、在 macOS 上安装与配置 nvm

自 macOS Catalina 开始，系统默认 Shell 已经从 Bash 变更为 Zsh。本节以当前主流的 Zsh 环境为例进行标准安装演示。

1. 确认前置命令行开发工具

nvm 在拉取和编译部分环境时需要依赖 Git 与基础 C/C++ 工具链。在终端中执行以下命令确认是否已经安装了 Xcode 命令行工具：

xcode-select --install

若系统弹窗提示安装，按提示点击确认安装即可；若终端提示 xcode-select: error: command line tools are already installed，则说明依赖已具备。

2. 执行官方安装脚本

官方明确不推荐使用 Homebrew 安装 nvm，因为 Homebrew 的更新机制常与 nvm 的内部版本管理产生冲突。请直接在终端运行官方发布的安装脚本（此处以稳定的 v0.39.7 为例）：

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

该脚本会将 nvm 核心源码克隆至当前用户根目录的 ~/.nvm 隐藏文件夹中。

3. 配置 Shell 环境变量

在绝大多数情况下，安装脚本会自动检测当前终端环境并将引导脚本写入配置文件。但由于部分 macOS 系统的 ~/.zshrc 文件初始不存在，导致配置未正确落盘。我们可以手动检查并补齐配置。

使用文本编辑器（例如 nano、vim）打开当前用户根目录下的 ~/.zshrc：

nano ~/.zshrc

在文件末尾确保包含以下环境变量与启动定义：

# NVM 基础路径与脚本载入
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

保存并退出编辑器后，执行重载命令使配置在当前终端立刻生效：

source ~/.zshrc

4. 验证安装结果

在终端中执行环境检查：

command -v nvm

示例输出：

nvm

三、在 Windows 上安装与配置 nvm-windows

Windows 环境下的安装重点在于清理遗留版本与处理符号链接权限。

1. 彻底卸载已有 Node.js

若你的电脑之前直接运行过 Node.js 官方安装包（MSI），在安装 nvm-windows 之前必须进行彻底清理，否则原有的 node 可执行文件会优先占领 PATH 环境变量，或者阻碍 nvm-windows 创建软链接：

• 打开「控制面板」->「程序和功能」，找到已有的 Node.js 并点击卸载。
• 手动检查并删除残留目录：C:\Program Files\nodejs（若存在）。
• 清理全局 npm 配置缓存：打开文件资源管理器，在地址栏输入 %APPDATA%，删除其中的 npm 与 npm-cache 文件夹。

2. 下载并运行 nvm-setup.exe

访问 GitHub 上的官方项目仓库 coreybutler/nvm-windows/releases，下载最新稳定版的 nvm-setup.exe 安装包。

双击安装向导进行安装，过程中的两个路径选择至关重要：

1. nvm installation path：nvm 程序主文件和下载的各个 Node 版本存放路径。默认通常为 C:\Users\用户名\AppData\Roaming\nvm。如果修改，请确保路径中绝不包含空格或中文（例如不要存放在带有空格的文件夹下）。
2. Set Node.js Symlink：指定 Node.js 符号链接路径。建议保持默认的 C:\Program Files\nodejs。nvm-windows 会自动将该目录注册进系统环境变量 PATH 中。

3. 权限配置：开启 Windows 开发者模式（避免每次提权）

由于 nvm-windows 需要在系统目录下创建符号链接，在默认安全策略下，非管理员身份运行终端切换版本时会触发错误：exit status 1: Access is denied。

推荐的长效解决方案是开启 Windows 的「开发者模式」，它允许普通用户无须 UAC 提权即可创建符号链接：

• 打开系统「设置」->「隐私和安全性」（或「更新与安全」）->「开发者选项」。
• 将「开发者模式」开关切换为开启。

若无法开启该模式，则后续在执行版本切换操作时，必须右键点击终端（PowerShell 或 CMD），选择「以管理员身份运行」。

4. 验证安装结果

关闭之前打开的所有命令行窗口，启动一个新的 CMD 或 PowerShell 窗口，执行：

nvm v

示例输出：

Running version 1.1.12.
Usage:
  nvm version
  nvm install <version> ...

能够正确输出版本号与使用帮助，表明 Windows 环境下的 nvm 已经就绪。

四、核心实操：日常版本管理与工程协同工作流

安装完成后，Mac 与 Windows 在多版本管理的核心操作命令上具有高度相似性，但在部分指令参数上略有差异。

1. 查询可安装的远程版本

在安装具体版本前，通常需要确认官方当前有哪些 LTS（长期维护）版本或指定的小版本号：

macOS：

# 查看官方所有历史版本（列表较长）
nvm ls-remote

# 仅筛选长期支持版本 (LTS)
nvm ls-remote --lts

Windows：

# 查看近期主流 LTS 及最新正式版列表
nvm list available

示例输出（Windows）：

|   CURRENT    |     LTS      |  OLD STABLE  | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
|    22.9.0    |   20.18.0    |   0.12.18    |   0.11.16    |
|    22.8.0    |   20.17.0    |   0.12.17    |   0.11.15    |
|    22.7.0    |   18.20.4    |   0.12.16    |   0.11.14    |

2. 安装指定的 Node.js 版本

确定需要安装的版本后，直接执行 nvm install <版本号>。支持指定完整版本号，或直接指定大版本：

# 安装 Node.js 20 的最新维护版
nvm install 20.18.0

# 安装旧项目专用的 Node.js 16
nvm install 16.20.2

# 在 Mac 上直接安装最新长期支持版
nvm install --lts

安装过程中，nvm 会自动下载对应的预编译二进制归档包以及对应配套的 npm 工具链，并在解压校验后存入对应本地目录。

3. 查看本地已安装的版本

随时可以查看当前机器上已经安装好的版本：

# macOS 命令
nvm ls

# Windows 命令
nvm list

示例输出（macOS）：

       v16.20.2
->     v18.20.2
       v20.18.0
default -> 20 (-> v20.18.0)

输出中箭头 -> 指向的条目代表当前终端会话正在使用的活跃版本。

4. 切换活跃版本

当需要切换到另一个项目所需的 Node 环境时，运行 nvm use：

nvm use 16.20.2

运行结果验证：

node -v
v16.20.2

npm -v
8.19.4

5. 设置默认版本（macOS）

在 macOS 上，每当你开启一个新的终端标签页时，nvm 会读取名为 default 的别名。如果不设置，新窗口可能会退回系统预置 Node 或找不到 Node。运行以下命令将常用版本设为默认：

nvm alias default 20.18.0

在 Windows 上，由于 nvm use 会修改全局持久化的符号链接，一旦执行 nvm use，除非下一次再次执行变更，否则新打开的所有窗口都会默认保持该版本。

6. 利用 .nvmrc 统一团队开发环境

在多人协同的前端项目中，常常由于团队成员各自电脑上的 Node 版本不一致，导致生成的 package-lock.json 频繁冲突，或者构建产物在不同机器上表现不一。

最佳实践是在工程根目录下创建一个名为 .nvmrc 的文本文件，文件内容仅写入该工程指定的 Node 版本号：

# 在工程根目录下创建 .nvmrc
echo "20.18.0" > .nvmrc

后续无论哪位开发者克隆了该工程，进入该目录后只需执行：

nvm use

在 macOS 环境下，nvm 会自动向上查找 .nvmrc 文件并切换至对应版本（若本地尚未安装该版本，终端会直接提示 nvm install 进行安装）。

五、常见问题排查与关键避坑指南

在多版本管理的实际使用中，有几个高频发生的边缘问题需要特别关注。

1. Windows 切换版本报错：exit status 1: Access is denied

原因： Windows 普通用户权限禁止随意修改系统级符号链接。

解决办法：

• 按上文第三节所述，在系统设置中启用「开发者模式」（推荐，一劳永逸）。
• 或者临时右键点击 Windows Terminal、PowerShell 或 CMD 图标，选择「以管理员身份运行」，在管理员终端中执行 nvm use <version>。

2. macOS 新开终端提示：zsh: command not found: nvm

原因： 环境变量未在 Zsh 的初始化链路中生效。常见于直接在 ~/.bash_profile 中写了配置，但当前终端跑的是 Zsh。

解决办法： 确认 ~/.zshrc 文件中完整存在 export NVM_DIR="$HOME/.nvm" 及相关的 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" 配置，并检查文件中是否有其他 export PATH 语句在 nvm 之后强行覆盖了系统路径。

3. 全局安装的 npm 命令行包丢失

许多初学者会疑惑：“为什么我之前在 Node 16 下全局安装了 yarn、pnpm 或 typescript，切换到 Node 20 后提示找不到命令？”

机制解释： 这正是 nvm 保证隔离性的核心设计。每个安装的 Node.js 版本都拥有完全独立的 node_modules 全局目录。在 Node 16 下全局安装的包绝不会污染 Node 20，这避免了因底层 Node C++ 插件二进制不兼容引发的崩溃。

应对方案：

• 在切换到新版本后，根据需要重新执行全局安装：npm install -g pnpm yarn。
• 推荐使用 Node.js 自带的 Corepack 工具（Node 16.13+ 内置），直接激活包管理器，无需频繁手动全局安装：

  corepack enable

4. 国内网络下载 Node 安装包超时或卡顿

nvm 默认从 Node.js 官方服务器（nodejs.org/dist）下载安装包，国内网络环境下有时会出现下载中断或连接重置。

Windows 解决方式：

直接编辑 nvm-windows 安装根目录下的 settings.txt 文件（或在终端运行命令配置）：

nvm node_mirror https://npmmirror.com/mirrors/node/
nvm npm_mirror https://npmmirror.com/mirrors/npm/

macOS 解决方式：

在 ~/.zshrc 中追加以下镜像环境变量配置：

export NVM_NODEJS_ORG_MIRROR="https://npmmirror.com/mirrors/node"

保存后执行 source ~/.zshrc，再次执行 nvm install 时即可走国内镜像源高速下载。

六、总结

使用 nvm 进行 Node.js 多版本管理是规范前端与全栈工程环境的基石。在 macOS 上，把握好 Shell 函数在 ~/.zshrc 中的加载时序，即可充分利用其窗口级隔离的灵活特性；在 Windows 上，彻底清理旧环境、指定纯净路径并开启开发者模式赋予符号链接创建权限，就能稳定发挥 nvm-windows 的全局版本调控能力。配合工程内部的 .nvmrc 版本约定，能够彻底根绝团队内部因 Node 版本不一引发的各种构建怪相与联调阻碍。