macOS下使用Homebrew或pkg安装包安装Node.js指南

一、选型决策：Homebrew 还是官方 .pkg 安装包？

在正式开始安装之前，了解两者的运作机制和后期维护差异，有助于你根据当前的开发需求和机器环境做出合适的选择。

Homebrew 是 macOS 上广泛使用的命令行包管理工具。如果你的 Mac 已经用于开发，并且安装了 Git、Python 等各类工具，通过 brew install node 安装 Node.js 是最自然的做法。Homebrew 会自动拉取预编译好的二进制文件（Bottle），并在系统更新时通过一条 brew upgrade 命令连同其他软件包一同完成无缝升级。

官方 .pkg 安装包 则是 Node.js 官方针对 macOS 提供的标准安装程序。它是一个自包含的安装包，双击后通过 macOS 原生安装器（Installer.app）一步步引导完成，直接将 node 运行时可执行文件、核心库和 npm 安装到系统的公共目录中。即使机器上没有任何开发工具链，也能够立刻完成部署。

二、安装前准备：确认 macOS 芯片架构

现代 macOS 存在两种主要的处理器硬件架构：Apple Silicon 芯片（如 M1、M2、M3、M4 系列芯片）以及早期的 Intel x86_64 处理器。确认芯片架构有助于我们理解后续的安装路径差异。

打开 macOS 自带的“终端”（Terminal.app），输入以下命令检查当前系统的架构：

uname -m

arm64

x86_64

在 Apple Silicon 芯片（arm64）下，Homebrew 的文件默认存放在 /opt/homebrew/ 目录下，以避免与 Intel 时代的 /usr/local/ 产生架构混淆；而在使用官方 .pkg 安装包时，不论何种芯片，安装器均统一写入 /usr/local/bin/。

三、方法一：使用 Homebrew 安装 Node.js

Homebrew 途径操作直接、流程自动化程度高，是前端与 Node.js 开发者在 Mac 上的首选方式。

步骤 1：确认 Homebrew 状态

在终端中确认 Homebrew 已经安装并处于可用状态：

brew --version

Homebrew 4.4.x
Homebrew/homebrew-core (git revision ...)

如果终端提示 command not found: brew，说明尚未安装 Homebrew，请先访问 Homebrew 官网获取安装脚本完成安装，或直接转至本文第四部分使用 .pkg 安装包。

步骤 2：选择 Node.js 版本分支

Node.js 官方版本分为 Current（最新特性版） 与 LTS（Long Term Support，长期支持版）。对于商业生产项目或需要高稳定性的开发环境，强烈建议安装处于活跃周期的 LTS 版本。

• 安装最新稳定版：直接使用 brew install node，Homebrew 会自动安装最新的稳定发布版本。
• 安装指定 LTS 版本：例如安装 Node.js 22 LTS 分支，可使用带版本后缀的配方：brew install node@22。

步骤 3：下发安装指令

以安装默认版本为例，在终端中直接运行以下命令：

brew update
brew install node

Homebrew 将自动拉取对应芯片架构的预编译 Bottle 包、关联依赖（如 icu4c、ca-certificates 等），并在下载完成后自动解压并建立软链接。

# 适用于 Apple Silicon 芯片的指定版本 PATH
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

四、方法二：使用官方 .pkg 安装包安装 Node.js

如果你的计算机暂未安装 Homebrew，或者希望获得图形化的标准安装体验，直接下载官方 .pkg 是最省心的途径。

步骤 1：从官网下载对应芯片架构的 .pkg 文件

打开浏览器，访问 Node.js 官方网站（https://nodejs.org/）。网站通常会自动侦测访问设备为 macOS，并展示两个主下载按钮：

• LTS 长期维护版（推荐大多数用户）：具有长达数年的稳定维护期，第三方 npm 生态插件兼容性最好。
• Current 当前发布版：包含最新的 ECMAScript 语法支持与前沿特性实验。

点击下载后，你将获得一个格式为 node-v*.pkg 的安装包。

步骤 2：运行图形安装向导

1. 在“访达”（Finder）中找到刚刚下载的 .pkg 文件，双击打开。
2. 弹出“安装 Node.js”向导窗口后，依次点击“继续”以接受软件许可协议。
3. 在“安装类型”界面，保持默认的“为这台电脑上的所有用户安装”，点击“安装”。
4. 此时系统会弹出 macOS 安全鉴权对话框，输入你的 Mac 开机密码或使用 Touch ID 指纹确认授权。
5. 等待进度条走完，当看到“安装成功”的绿色对勾提示时，点击“关闭”即可。

步骤 3：理解 .pkg 的系统落地点与环境变量

许多初学者感到好奇：为什么 .pkg 安装完成后，打开任何终端窗口都能直接识别 node 和 npm 命令，而无需手动配置 PATH 环境变量？

原因在于，.pkg 安装器将可执行程序直接写到了 /usr/local/bin/ 目录。而在 macOS 的标准系统配置中，/etc/paths 文件默认已将 /usr/local/bin 置于系统检索路径之中，因此任何新建的终端会话都能无感知地调用该路径下的二进制文件。

五、安装结果验证与编写第一个运行测试

无论采取上述哪一种方式完成安装，都必须进行最终的功能与路径验证。

1. 基础版本与命令路径核验

重新打开一个终端窗口（确保加载最新的环境变量），依次执行以下检查命令：

node -v

v22.12.0

npm -v

10.9.0

which node

/opt/homebrew/bin/node

/usr/local/bin/node

2. 编写并运行测试脚本

我们可以通过终端创建一个简单的测试脚本 test_env.js，验证 Node.js 运行时以及底层 V8 引擎在 macOS 上的工作状态：

// 验证脚本 test_env.js 内容：
const os = require('os');

console.log("-----------------------------------------");
console.log("Node.js 运行环境验证成功！");
console.log("Node 版本: " + process.version);
console.log("执行架构: " + process.arch);
console.log("操作系统: " + os.type() + " " + os.release());
console.log("CPU 核心数: " + os.cpus().length);
console.log("-----------------------------------------");

在终端中执行测试命令：

node test_env.js

-----------------------------------------
Node.js 运行环境验证成功！
Node 版本: v22.12.0
执行架构: arm64
操作系统: Darwin 24.x.x
CPU 核心数: 8
-----------------------------------------

六、常见问题排查与关键配置

在日常开发使用中，初学者常常会遇到全局权限受阻或终端找不到命令的情况。以下整理了最核心的排查应对方案。

1. 全局安装报 EACCES 权限错误（尤其是 .pkg 方式）

当你在终端中执行诸如 npm install -g yarn 或 npm install -g typescript 时，如果出现类似以下报错：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/...
npm ERR! Error: EACCES: permission denied

原因解释：官方 .pkg 安装包将 npm 的全局根目录默认设在 /usr/local/lib/node_modules/，该目录归 root 用户所有。许多人会习惯性使用 sudo npm install -g ... 来解决，但这极不安全，会造成系统文件权限混乱并埋下安全隐患。

标准规范解法：将 npm 全局包安装前缀修改至用户个人主目录下（即 ~/.npm-global）：

1. 在个人主目录下创建全局模块专属文件夹：

   mkdir -p ~/.npm-global

2. 配置 npm 将前缀指向该目录：

   npm config set prefix ~/.npm-global

3. 将该目录的 bin 路径加入 Shell 环境变量（以 ~/.zshrc 为例）：

   echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

完成配置后，后续所有 npm install -g 命令均会在用户主目录下安全执行，无需任何 sudo 权限。

2. 终端提示 command not found: node

如果在执行 node -v 时提示找不到命令，通常属于 PATH 环境变量未生效：

• 如果是 Homebrew（Apple Silicon 芯片）：请检查 ~/.zshrc 中是否包含 eval "$(/opt/homebrew/bin/brew shellenv)"。若未注入，终端将无法定位到 Homebrew 的 bin 目录。
• 如果配置了 ~/.zshrc，请确保执行过 source ~/.zshrc 或完全关闭终端窗口后重新打开。

3. 版本升级与彻底卸载方案

随着项目推进，你需要对 Node.js 进行升级或完全重装清理：

• Homebrew 升级与卸载：
  升级命令：brew update && brew upgrade node
  卸载命令：brew uninstall node && brew cleanup
• 官方 .pkg 升级与卸载：
  升级：直接下载新版本 .pkg 双击覆盖安装即可。
  彻底卸载：由于 .pkg 没有提供卸载界面，如需彻底移除，可在终端中执行以下清理命令（需要 sudo 权限确认）：

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

七、总结

在 macOS 下安装 Node.js 是一项基础而关键的环境配置步骤：

• 如果你正在搭建常规开发机，且已在终端中使用各类包管理工具，Homebrew 提供了出色的依赖自治与简便的一键更新体验，是日常开发的高效之选。
• 如果你是初次接触 Node.js 开发，希望避免前期配置其他工具链，直接从官网下载 .pkg 安装包 能够以最短的路径完成开箱即用。配合合理的 npm 全局路径重定向，同样能保障长期开发的稳健性。

掌握这两种途径的安装逻辑、目录落点与权限机制，能帮助你在遇到环境变动或依赖报错时迅速找准根因，为后续的 JavaScript 与全栈工程开发打下坚实的基础。