🍎 Mac 正确安装 nvm 并管理 Node.js —— 小白完全指南（附避坑）

📌 为什么要写这篇？

很多教程让你：

“去 Node 官网下载 pkg 安装”

结果半年后你会遇到：

• ❌ EACCES: permission denied（全局包装不上，要 sudo）
• ❌ 项目 A 要 Node 18，项目 B 要 Node 20，你只能卸了重装
• ❌ Vite / Rolldown 提示 Node 版本不兼容（就是你之前碰到的）

👉 这些问题不是你菜，是安装方式错了。

---

一、为什么 Mac 一定要用 nvm？（小白能听懂版）

❌ 不推荐方式

方式	问题
Node 官网 .pkg	装进 /usr/local，需 sudo，难切换版本
brew install node	Homebrew 装 Node 不推荐用于 nvm 用户（nvm 官方说明）

✅ 正确方式：nvm（Node Version Manager）

nvm = Node 版本管理器

打个比方：

• 系统自带 / pkg 装的 Node ≈ 只有一双鞋
• nvm ≈ 鞋柜，你想穿 18 码换 18，想穿 20 码换 20

nvm 的好处：

• ✅ 一台 Mac 同时装 Node 16 / 18 / 20
• ✅ 不同项目自动切换版本（.nvmrc）
• ✅ 全局包装包不需要 sudo
• ✅ 完全规避你之前遇到的 Vite + Node 22.11 不兼容问题

---

二、前置检查（先做）

1️⃣ 确认 Shell

macOS 10.15+ 默认是 zsh

echo $SHELL
# /bin/zsh ✅
# /bin/bash ❗（老系统，按 bash 处理）

2️⃣ 安装 Xcode Command Line Tools（必须）

nvm 和某些 Node 编译依赖它需要：

xcode-select --install

如果提示 already installed，可以直接跳过

---

三、安装 nvm（官方方式 · 最稳）

✅ 以下内容来自 nvm 官方 README（你提供的文档）

✅ Step 1｜执行安装脚本

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

脚本会做三件事：

1. 把 nvm clone 到 ~/.nvm
2. 自动把初始化代码追加到 ~/.zshrc（或 ~/.bashrc）
3. 设置 NVM_DIR

---

✅ Step 2｜让 nvm 生效

如果是 zsh（绝大多数 Mac）：

source ~/.zshrc

如果是 bash：

source ~/.bashrc
# 或
source ~/.bash_profile

---

✅ Step 3｜验证安装成功（很重要）

command -v nvm

✅ 正确结果（必须看到这个）：

nvm

❌ 如果 无任何输出：

• 检查 ~/.zshrc是否包含下面内容
• 没有就手动加（见下方）

---

四、手动补全 nvm 初始化（如脚本未自动写入）

打开配置文件：

open -e ~/.zshrc

确保文件里有这三行（nvm 官方要求）：

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

保存后执行：

source ~/.zshrc
command -v nvm

---

五、用 nvm 安装 Node（正确姿势）

✅ 安装符合 Vite / Vue 3 的 Node 版本

nvm install 20.19.0
nvm alias default 20.19.0
nvm use 20.19.0

验证：

node -v
# v20.19.0

npm -v

✅ 这个版本满足：

• Vite ✅（要求 ≥20.19 或 ≥22.12）
• Rolldown ✅（原生 binding 正常）
• Spring Boot + Vue 实战 ✅

---

✅ 常用 nvm 命令（新手必记）

命令	作用
nvm ls	查看已安装版本
nvm ls-remote	查看可安装版本
nvm install 18	安装最新 18.x
nvm use 18	切换版本
nvm alias default 20	设置默认
nvm uninstall 16	卸载指定版本

---

六、项目级自动切换 Node 版本（进阶 · 强烈推荐）

进入你 Vue 项目根目录：

echo "20.19.0" > .nvmrc

以后只要：

nvm use

nvm 自动切到 20.19.0

（配合 zsh hook 可实现 cd自动切换，见 nvm README）

---

七、Mac 常见报错 & 解决

❌ nvm: command not found

→ ~/.zshrc没 source 或没写初始化代码

✅ 按 第四节 手动补全并重载

❌ 之前用 pkg / brew 装过 Node

→ 检查：

which node

✅ 应该显示：

/Users/xxx/.nvm/versions/node/v20.19.0/bin/node

❌ 若是 /usr/local/bin/node→ 建议卸载系统 Node，只用 nvm

❌ Apple Silicon (M1/M2/M3) 装老 Node (<14) 失败

→ nvm README 说明：需用 Rosetta 或 ≥16 版本

✅ 实战项目推荐直接用 Node ≥16（你用 20.19 没问题）