macOS 下 Homebrew 安装 Node.js 与多版本管理实践

脚本专家

对于 macOS 开发者来说，Homebrew 是最常用的包管理工具之一，用它安装 Node.js 能自动处理依赖并简化后续升级。本文将梳理从安装、验证到版本切换、卸载的完整流程，同时解决常见权限和路径问题。

1. 确认或安装 Homebrew

首先确保系统已安装 Homebrew，执行以下命令检查版本：

2. brew --version

复制代码

若返回版本号则说明已安装；否则运行官方安装脚本：

2. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

复制代码

该脚本会自动安装 Homebrew 并配置路径。

2. 安装 Node.js

方案一：安装最新稳定版（推荐）
最直接的方式是使用 brew install 命令，默认安装当前最新的 LTS 版本：

2. brew install node

复制代码

此命令会同时安装 npm 和 npx。

方案二：安装特定版本
如果项目需要固定版本（如 Node 18.x），先搜索可用版本：

2. brew search node

复制代码

然后安装指定版本：

2. brew install node@18

复制代码

注意：Homebrew 将版本号放在 @ 后面，安装后 binary 会指向 /usr/local/opt/node@18 目录。

3. 安装后验证

运行以下命令确认安装成功：

2. node -v
3. npm -v
4. npx -v

复制代码

若版本号正确输出，则安装正常。

4. 环境变量配置（仅针对特定版本安装）

使用 brew install node@18 这类命令安装的特定版本，默认不会被加入 PATH。需要手动添加环境变量。以 zsh 为例（macOS 11+ 默认 Shell）：

2. echo 'export PATH="/usr/local/opt/node@18/bin:$PATH"' >> ~/.zshrc
3. source ~/.zshrc

复制代码

若使用 bash，则将上述中的 .zshrc 替换为 .bash_profile。

5. 升级 Node.js

先更新 Homebrew 源：

2. brew update

复制代码

然后升级 Node：

2. brew upgrade node

复制代码

如果之前安装的是特定版本（如 node@18），升级命令同理：

2. brew upgrade node@18

复制代码

6. 多版本切换管理

当需要在多个项目中使用不同 Node 版本时，推荐使用 n 或 nvm 这类版本管理工具。

使用 n（基于 npm 的版本管理）
安装 n：

2. npm install -g n

复制代码

安装特定版本（例如 16.13.0）：

2. n 16.13.0

复制代码

交互式切换版本（按上下键选择）：

2. n

复制代码

使用 nvm（Node Version Manager）
通过 Homebrew 安装 nvm：

2. brew install nvm

复制代码

安装完成后，根据提示将 nvm 初始化脚本添加至 Shell 配置文件。例如 zsh：

2. echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
3. echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && . "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrc
4. source ~/.zshrc

复制代码

之后即可使用 nvm 安装和切换版本：

2. nvm install 14
3. nvm use 14

复制代码

7. 卸载 Node.js

若需完全移除 Homebrew 安装的 Node：

2. brew uninstall node

复制代码

如果之前安装了特定版本，如 node@18：

2. brew uninstall node@18

复制代码

彻底删除残留的全局模块和 npm 缓存：

2. rm -rf /usr/local/lib/node_modules
3. rm -rf ~/.npm

复制代码

常见问题排查

权限错误：如果执行 brew 或 node 命令时提示权限不足，通常是因为 /usr/local 目录被 root 拥有。可运行以下命令将所有权交给当前用户：

2. sudo chown -R $(whoami) $(brew --prefix)/*

复制代码

命令未找到：如果 brew、node 等命令找不到，检查 Shell 配置文件是否包含 Homebrew 路径。zsh 用户请确认 ~/.zshrc 中有如下行：

2. export PATH="/usr/local/bin:$PATH"

复制代码

然后重新加载：

2. source ~/.zshrc

复制代码

node 与 npm 版本不匹配：极少数情况下 homebrew 安装后 node 和 npm 版本显示不一致，可通过 postinstall 修复：

2. brew postinstall node

复制代码

总结：使用 Homebrew 安装 Node.js 是 macOS 上最推荐的方案，它自动处理依赖、方便升级，并且可以与 n/nvm 配合实现多版本管理。安装特定版本后别忘了手动配置 PATH，否则终端无法直接调用。

热心网友2

感谢分享这么详细的教程！步骤清晰，覆盖了从安装到多版本管理的各种场景，特别是“安装特定版本后要手动配置 PATH”这点很实用，新手容易忽略。另外文末的常见问题排查也很贴心，收藏了！