macOS下通过Homebrew或pkg安装包安装Node.js教程

图 1：macOS 下安装 Node.js 的两种核心方式概览

在 macOS 系统上搭建 JavaScript / TypeScript 服务端或前端开发环境，Node.js 是最基础的核心依赖。官方和社区在 macOS 上提供了两种最主流的直装方案：一种是面向日常开发、高度可维护的 Homebrew 包管理器，另一种是面向开箱即用、免配命令行的 .pkg 官方图形安装包。本文将针对这两条路径展开具体的操作步骤、底层路径差异与常见问题排查，帮助读者根据自身使用场景完成稳妥配置。

一、两种安装方式的核心差异与选型依据

在开始敲击终端命令或下载文件之前，理清两种安装机制对后续维护至关重要：

• Homebrew 途径：将 Node.js 及其依赖作为系统包管理，安装路径在当前用户拥有读写权限的目录（Apple Silicon 芯片为 /opt/homebrew，Intel 芯片为 /usr/local）。支持一键通过 brew upgrade 更新，且方便在多版本之间通过配方切换，是终端使用者和开发人员的首选。
• 官方 .pkg 途径：由 Node.js 官方构建的 macOS 标准安装程序，通过图形向导一路点击完成。它默认将 node 和 npm 可执行文件写入 /usr/local/bin，将模块库写入 /usr/local/lib。适合只需要单版本运行环境、不打算在本地维护复杂包管理器的用户。

图 2：Homebrew 与官方 .pkg 安装方式对比与决策矩阵

综合来看：如果你的 Mac 主要用于代码开发或已有 Homebrew，优先推荐使用 方式一（Homebrew）；如果你只是为了运行特定脚本，不想额外安装包管理器，选择 方式二（.pkg） 即可。

二、方式一：通过 Homebrew 安装 Node.js

Homebrew 是 macOS 下事实上的标准包管理器。使用 Homebrew 安装 Node.js，无需手动解压或手动配置路径符号链接。

图 3：Homebrew 安装与配置流程步骤分解

1. 前置准备：确认 Homebrew 状态

打开 macOS 的“终端”（Terminal）或 iTerm2，首先确认 Homebrew 是否可用并更新软件索引仓库：

brew update

如果输出显示 Already up-to-date. 或拉取了最新的 Formulae 列表，则说明 Homebrew 工作正常。若终端提示 zsh: command not found: brew，说明尚未安装 Homebrew，可先执行官方脚本安装或直接改用下文的 .pkg 方案。

2. 安装最新稳定版本（Current）

如果项目没有特殊的旧版本要求，直接执行以下命令安装默认的 Node.js 稳定版：

brew install node

Homebrew 会自动解析 Node.js 所需的底层依赖（如 openssl、brotli、c-ares 等），完成编译或拉取预编译的瓶子（bottles）二进制，最后自动创建全局软链。

3. 安装指定 LTS 长期支持版（如 Node.js 20）

许多生产项目为了稳定性，会指定使用特定 LTS 版本（例如 node@20 或 node@18）。Homebrew 提供了独立维护的配方：

# 查找可用的特定版本配方
brew search node@

# 安装指定的 LTS 20 版本
brew install node@20

brew link --overwrite --force node@20

echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

三、方式二：通过官方 .pkg 安装包安装

对于初学者或无需频繁切换版本的机器，官方提供的 .pkg 安装包提供了最直观的体验。

图 4：官方 .pkg 图形安装向导流程与系统落盘架构

1. 下载官方安装包

在浏览器中访问 Node.js 官方网站（https://nodejs.org）。首页通常展示两个版本：

• LTS（Long Term Support，推荐）：长期支持版，具备最完善的生态库兼容性和稳定性。
• Current（最新特性版）：包含最新的 JavaScript 语法支持和实验性 API，适合尝鲜。

点击 LTS 版本的 macOS 安装包下载按钮，会下载形如 node-v20.x.x.pkg 的文件。

2. 执行图形化向导

1. 在“访达”（Finder）的“下载”目录中双击该 .pkg 文件，启动 macOS 安装器。
2. 在“介绍”界面点击“继续”，并在接下来的“软件许可协议”界面点击“同意”。
3. 在“安装类型”界面保留默认的“Macintosh HD”安装位置，点击“安装”。
4. 系统会弹出授权确认窗口，输入当前 macOS 用户的登录密码或通过触控 ID（Touch ID）验证。
5. 安装程序将核心文件部署到 /usr/local/bin 与 /usr/local/lib，完成后提示“安装成功”。

四、安装后验证与环境测试

无论选择哪种方式安装，完成后都需要验证可执行文件是否已正确定位到环境变量中。

1. 检查版本与路径

重新打开一个新的终端窗口（确保加载最新环境变量），依次运行：

# 查看 Node.js 版本
node -v
# 示例输出：v20.12.0

# 查看随附安装的 npm 版本
npm -v
# 示例输出：10.5.0

# 查看实际调用的 node 所在绝对路径
which node

根据安装方式的不同，which node 的输出应当符合以下规律：

• Homebrew（Apple Silicon 芯片）：/opt/homebrew/bin/node
• Homebrew（Intel 芯片）：/usr/local/bin/node
• 官方 .pkg 安装包：/usr/local/bin/node

2. 执行一段简单的测试代码

可以直接进入 Node.js 的 REPL 交互环境，或执行单行脚本测试输出：

node -e 'console.log("Node.js 在 macOS 上运行正常:", process.version, process.arch)'

终端会输出当前运行版本及系统架构（如 arm64 或 x64），确认环境正常解析并运行代码。

五、常见问题与注意事项排查

在实际使用中，有三个高频问题最容易给用户带来困扰：

图 5：Node.js 安装后环境排错与全景诊断图

1. 终端提示 zsh: command not found: node

这说明 Node.js 的可执行文件目录未被收录进当前 Shell 的 PATH 中。常见于新配环境的 Apple Silicon 芯片机器：

• 如果是 Homebrew 安装，确保在 ~/.zprofile 中注入了 brew 环境：

  echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
  source ~/.zprofile

• 如果是 .pkg 安装，检查 /usr/local/bin 是否在 PATH 中：

  echo $PATH

  若不在，可向 ~/.zshrc 中添加 export PATH="/usr/local/bin:$PATH" 并重载。

2. 全局安装包权限报错：EACCES: permission denied

使用 .pkg 安装的用户在运行 npm install -g <package> 时，经常遇到 EACCES 权限错误。切忌使用 sudo npm install -g，因为提权安装会导致模块文件归属 root，产生安全风险并打乱后续权限。

推荐的规范解法是将 npm 全局目录重定向到用户主目录：

# 1. 在当前用户根目录下创建专属全局安装目录
mkdir ~/.npm-global

# 2. 修改 npm 全局安装前缀
npm config set prefix '~/.npm-global'

# 3. 将新目录追加至 PATH 环境变量
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

# 4. 刷新配置
source ~/.zshrc

3. 如何彻底卸载或更换安装方式

如果需要在 Homebrew 与 pkg 之间切换，建议先将旧环境清理干净：

• 清理 Homebrew 安装：

  brew uninstall --ignore-dependencies node

• 清理官方 .pkg 安装（由于 .pkg 没有自带卸载向导，需手动删除对应路径）：

  sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx
  sudo rm -rf /usr/local/lib/node_modules
  sudo rm -rf /usr/local/include/node
  sudo rm -rf /usr/local/share/man/man1/node.1

六、总结与日常使用建议

在 macOS 系统中，Node.js 的安装并不复杂。对于绝大多数开发者而言，借助 Homebrew 管理版本是最省心、与开发工具链结合最紧密的方式；而 .pkg 官方安装包则是在未配置命令行包管理器时最迅速的备选手段。安装完成后，务必确认 node -v 与 npm -v 命令输出正确，并合理配置全局包目录权限，即可保障后续工程的高效稳定运行。