Mac 上 Node 版本管理（brew + nvm 共存方案）

背景说明

• 本机已通过 brew 安装：node@18（日常开发主力）、node@20

• 需求：大部分时间使用 Node18；仅部分工具临时需要 Node20

• 目标：两套环境共存，不破坏原有开发环境，不出现版本混乱

核心概念

1. brew node ：系统级 Node，安装在/usr/local，就是你现在日常用的 v18.19.0

2. nvm node ：用户目录下的多版本管理器，安装到~/.nvm/versions/node

3. nvm use 20：仅当前这一个终端窗口临时生效，关闭窗口就失效，不会改变全局默认

4. nvm alias default xxx：控制所有【新开终端】默认使用哪个 Node 版本

5. ⚠️重要：不要设置 default 为 20！否则所有新开终端全部变成 Node20，老项目会报错

环境隔离说明

• brew 的 node 和 nvm 的 node 不会发生文件冲突，依靠环境变量 PATH 优先级接管

• nvm 激活时，brew 的 node 会被临时屏蔽；nvm 未激活，自动回到 brew 系统 node

• npm 全局包互相隔离：brew 的全局包和 nvm 的全局包是两套，不能互相共用

---

一、一次性初始化操作（只执行一遍）

1. 安装 nvm 管理的 Node20

brew 已经装了 node20，但那属于 system，我们再用 nvm 下载一份 node20 用于临时使用

# 安装 node20 LTS（只执行一次）
nvm install 20

2. 设置新开终端默认版本【关键！防止踩坑】

# 设置默认是 system，也就是brew的node18
nvm alias default system

3. 校验初始化结果

# 查看nvm管理的版本列表
nvm list

预期输出：

       v20.20.2   #nvm管理的
->       system   #当前使用的
default -> system   #默认的
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v20.20.2) (default)
stable -> 20.20 (-> v20.20.2) (default)

# 新开一个全新终端窗口执行
node -v

✅预期输出：v18.19.0，代表默认依旧是你日常开发的 Node18，初始化完成。

---

二、日常使用操作流程

场景 1：正常业务开发（使用 Node18，brew system）

新开终端，不需要执行任何 nvm 命令，原生就是 node18

node -v
# v18.19.0 直接写代码、跑项目即可

场景 2：需要 Node20，运行 需要node20 的工具（临时切换）

✅最佳实践：单独开一个新终端窗口做这件事，不要在写业务的终端切换版本

# 在这个独立终端窗口执行，仅本窗口生效
nvm use 20

# 校验版本
node -v
# 输出 v20.x.x

# 执行需要node20的业务命令
xxxx --help

两种复原方式二选一

1. 最简单：直接关闭这个终端窗口，环境自动复原，什么都不用敲

2. 如果不想关窗口，手动切回系统版本

nvm use system
node -v
# 变回 v18.19.0

❗千万不要：把写业务代码的终端长期 use 20，会导致旧项目依赖异常。

场景 3：已经在 use 20 的窗口，临时切回 18 测试

nvm use system
node -v
# v18.19.0

---

三、关键避坑清单（高频踩坑点）

1. nvm use 20 只对当前窗口生效！关闭窗口全部丢失，不是全局永久切换

2. 禁止执行 nvm alias default 20，执行后所有新终端默认 node20，老项目会炸

3. npm 全局包隔离问题

   • brew‑node18 下npm install -g xxx，这个全局工具在 nvm‑node20 环境找不到

   • nvm‑node20 环境需要全局工具，要重新执行npm install -g 包名

4. 修改完版本后验证，务必新开终端窗口测试，旧终端会缓存旧环境变量

5. 不要同时操作brew link node@20 和 nvm use 20，属于重复操作，无收益

6. nvm 不会删除 brew 安装的 node@18/node@20，磁盘两份同时保留，随时可以切回 system 使用 brew 版本

---

四、兜底方案：不想使用 nvm，只用 brew 来回切换版本

缺点：每次手动 link/unlink，容易忘记切回 18，适合临时应急

# 切换到 node20
brew unlink node@18
brew link node@20 --force

# 执行需要node20的工具
xxxx --help

# 使用完毕，务必切回18，否则后续开发全部跑在node20
brew unlink node@20
brew link node@18 --force

---

五、快速命令速查表

命令	作用
nvm list	查看所有 nvm 识别的 node 版本
nvm install 20	nvm 下载安装 node20
nvm use 20	当前窗口临时切换 nvm 的 node20
nvm use system	当前窗口切回 brew 的 node18
nvm alias default system	设置新开终端默认使用 brew node18
node -v	查看当前终端正在生效的 node 版本

使用口诀：

日常开发啥也不动，新开终端就是 18；

需要 20 就开新窗口，nvm use 20；

用完直接关窗口，环境自动复原。