如果你在 Mac 上写过两年代码，或者只是频繁折腾软件，应该绕不开 brew 这个名字。它是 macOS 上最主流的软件包管理工具，官方名字叫 Homebrew，平时大家直接叫 brew。简单说，brew 就像一个“应用商店”，不过它面向的不是手机 App，而是命令行工具和开发环境：git、python、mysql、nginx、openjdk，一条命令就能装好，升级和卸载也由它统一接管。这篇文章就以“Mac 安装 brew”为主线，把从零到能正常使用，再到后续常见报错如何排查的完整流程讲清楚。不管你是刚换 Mac 的新手，还是已经装了但经常遇到坑的老用户，都可以对照着操作。
1. 为什么 macOS 需要 brew：包管理器解决了什么问题
1.1 没有 brew 的“原始时代”
在 brew 出现之前，在 Mac 上装开发工具是比较痛苦的。以装个 Python 为例，正常路径是打开浏览器、搜索官网、下载 pkg 安装包、双击安装、填管理员密码，装完之后还要自己处理 PATH。想升级？把旧版删掉，再下载新版重来一遍。更麻烦的是依赖：装 A 软件之前要先装 B 库，B 库又依赖 C，手动管理这些关系很容易把系统环境搞乱。
brew 把这一整套流程变成了“包管理器”的标准模式。它把软件打包成了一个个 formula（命令行工具）和 cask（图形应用），并记录它们的依赖关系。你执行 brew install python 时，它会自动把 python 的编译依赖、运行库也一并处理掉。装完之后，升级用 brew upgrade python，卸载用 brew uninstall python，所有东西都在一个可追踪的清单里。这种体验和 iPhone 上从 App Store 装应用很接近，区别是 brew 帮你同时管了“底层依赖”和“应用本体”。
我用了 brew 大概八九年，换过几台 Mac，每次新机器到手第一步都是先把 brew 装上，再通过它批量装回自己惯用的工具。这个过程非常省心，也几乎是 macOS 开发者的默认起手式。所以第一步，理解 brew 是什么，比急着跑安装命令更重要。
1.2 brew 的本体：brew、cask、services 如何各司其职
brew 这个词有时候指整个 Homebrew 工具链，但它实际包含三个相对独立的部分。最核心的是 brew 本体，负责安装和卸载命令行工具；Homebrew Cask 负责安装带图形界面的应用，比如 Chrome、VS Code、iTerm2，命令是 brew install --cask 应用名；Homebrew Services 负责管理后台服务，比如装完 nginx 或 mysql 之后，可以用 brew services start nginx 让它在后台持续运行。
这三块的安装目录也不一样。命令行工具默认装进 Homebrew 的前缀目录，Apple Silicon 机器上是 /opt/homebrew，Intel 机器上是 /usr/local；Cask 安装的图形应用大部分会进 /Applications；services 则统一管理那些需要常驻的后台进程。理解这个结构，后面遇到“文件跑哪里去了”“为什么 brew list 里看不到某个软件”这类问题，就能很快定位。
对于刚接触 brew 的人来说，暂时不需要记太多，只用知道：装命令行工具用 brew install，装图形应用加 --cask，管后台服务用 brew services。三个命令覆盖了 90% 的使用场景。
2. 安装前的准备工作：先搞清芯片、系统和依赖
2.1 确认 Mac 芯片架构与系统版本
安装 brew 之前，先花十几秒认清自己这台机器的底细，能省掉后面一大堆弯路。第一个关键信息是芯片架构。点击屏幕左上角苹果图标，选择“关于本机”，这里能看到芯片一栏——如果写着 Apple M1、M2、M3 这类，那就是 Apple Silicon；如果写着 Intel Core i5/i7，那是 Intel 机型。更准确的办法是打开终端执行 uname -m，Apple Silicon 会输出 arm64，Intel 输出 x86_64。
第二个信息是系统版本，终端执行 sw_vers 就能看到。Homebrew 对 macOS 版本有最低要求，当前版本一般要求 macOS 14 或更高（具体以官方仓库说明为准），较早的系统虽然也能装上旧版 brew，但后续软件源和预编译包都会受限。如果你在“关于本机”里看到系统已经很老，建议优先考虑升级系统，而不是强行装新版本 brew。
为什么芯片架构这么重要？因为 Homebrew 按架构区分安装路径和预编译包。Apple Silicon 上公式默认装在 /opt/homebrew，Intel 上装在 /usr/local。如果你在 M 系列芯片上误用了为 Intel 准备的安装方式，后面极容易遇到路径找不到、二进制版本不对、运行报错等一系列问题。
2.2 提前安装 Xcode Command Line Tools
Homebrew 的安装脚本在正式安装前，会先检查系统里是否已经装了 Xcode Command Line Tools（命令行开发者工具）。这套工具包含 git、clang 编译器、make 等基础组件，brew 本身和很多 formula 的编译过程都依赖它。好消息是，你不需要为此安装完整的 Xcode（那是个好几个 G 的大块头），只装命令行工具就够了。
方法很简单，打开终端输入 xcode-select --install，系统会弹出一个安装窗口，点击“安装”，然后等它下载完成即可。这个过程一般几分钟，取决于网络速度。安装完可以执行 xcode-select -p 验证，能看到 /Library/Developer/CommandLineTools 这类路径就说明没问题。
有时候你之前装过 Xcode 或命令行工具，再执行 xcode-select --install 会提示“command line tools are already installed”，那就直接跳过。还有个小细节：如果系统提示找不到 git，通常是命令行开发者工具不完整，重新跑一次 xcode-select --install 往往能解决。
2.3 账号权限、用户目录与磁盘规划
brew 的官方安装脚本在部分场景下会需要管理员权限，所以安装前确认你的当前账号是管理员账号，并且记得登录密码。执行命令时一旦提示 sudo 请输入密码，输入即可。如果当前是普通用户账号，先去“系统设置-用户与群组”里确认权限，避免装到一半权限不足。
另外有个比较隐蔽的坑：如果用户的个人目录放在外部磁盘或者网络磁盘上，brew 安装脚本会给出警告，某些依赖的编译过程也容易出错。最稳妥的做法是把用户主目录放在 Mac 内置硬盘上，再执行安装。还有就是留意磁盘剩余空间，brew 本体加上命令行工具，占用并不大，但如果接下来要装很多软件，留出几十 G 的可用空间会比较从容。
这些都是我踩过的细节问题。曾经有一次因为用户目录挂在外置硬盘上，brew 装 git 时编译步骤反复失败，折腾了半小时，最后把目录迁回内置盘一次通过。所以别小看安装前的准备，很多时候报错与 brew 本身无关，环境问题才是大头。
3. 执行安装：官方脚本与镜像源加速
3.1 官方脚本安装的标准姿势
安装 brew 的方式有不少，官方推荐的是直接执行远程脚本。在终端里粘贴下面这行命令然后回车：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"这个脚本会做几件事：检查系统版本和芯片架构；再次检查命令行工具是否就绪；把你当前登录的普通用户目录归为 brew 目录的所有者；然后从 GitHub 拉取 brew 本体仓库，再下载必要的初始组件。整个过程会在终端里滚动输出大量日志，结尾出现 “Installation successful” 就说明装好了。
需要说明的是，curl 后面的 -fsSL 参数含义是：失败时报错、遇到 HTTP 错误不输出、静默跟随跳转。如果断网或者网络不稳定，你会直接看到 curl 报错，而不会拿到一个半截安装。这种设计对用户是友好的，发现问题可以立刻重来。
官方脚本默认的下载地址是 GitHub。如果当前网络访问 GitHub 比较顺畅，整个过程通常会非常快；如果网络环境一般，下载 brew 本体和后续更新仓库时容易卡住。这也就是为什么后面要单独讲镜像源的原因。
3.2 网络慢的解法：环境变量换镜像源
不少同学的 brew 安装失败，其实不是命令写错，而是从 GitHub 下载资源太慢，或者连接直接被重置。这里最常用的解法是：在跑官方脚本之前，先把下载地址换成开源镜像站。brew 提供了环境变量来覆盖默认连接地址，其中最常用的有四个：HOMEBREW_BREW_GIT_REMOTE 控制 brew 本体仓库，HOMEBREW_CORE_GIT_REMOTE 控制核心 formula 仓库，HOMEBREW_API_DOMAIN 控制 JSON API 接口，HOMEBREW_BOTTLE_DOMAIN 控制预编译包（bottle）的下载地址。
以中科大开源镜像站为例，打开终端执行以下命令，再跑官方安装脚本：
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git" export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"实测下来，在 GitHub 直连很慢的网络下，这种方式能把安装时间从几十分钟压缩到几分钟。值得提醒一句：镜像站的地址会不定期调整，比如清华、中科大、阿里云的路径格式并不完全一样，每次安装前先去镜像站官网看一眼最新的路径，是最稳的做法。
还要注意，这些 export 只是对当前终端窗口生效。如果你开了一个新窗口，环境变量就不存在了，所以要么每次在同一个窗口里安装，要么把 export 写进 shell 配置文件（.zshrc 或 .bash_profile）。后面讲安装完成后的持续换源时，我会再给一个更规范的做法。
3.3 安装要花多久：时间预期与进度判断
经常看到有人问“macOS 安装 brew 要多久”。这个问题很难给出一个统一数字，因为主要瓶颈不在计算，而在网络。如果直连 GitHub 且速度不错，完整安装 brew 本体大概 3 到 10 分钟；如果网络一般，可能要二三十分钟；如果卡在一个下载点长时间不动，基本就是网络问题，赶紧换方案，不要死等。
安装过程中你会看到很多输出，比如 “==> Tapping homebrew/core” 和 “Cloning into” 等字样。如果一个阶段停留超过十分钟没有任何变化，建议直接 Ctrl+C 中断，检查网络或切换镜像源后重试。死等不会等来结果，尽早换路才高效。
另外，第一次安装后通常会自动执行 brew update，把本地索引更新到最新。这一步同样受网络影响。如果你只想先把 brew 装好，可以在环境变量里加入 HOMEBREW_NO_AUTO_UPDATE=1，暂时关闭自动更新，等装好后再手动决定是否更新。
4. 安装完成后的收尾：PATH、验证与换源
4.1 把 brew 写进 shell 环境变量
安装脚本结束后，终端末尾会给出两行“Next steps”提示，告诉你还需要执行类似下面的命令，把 brew 的可执行文件路径加进 shell 环境变量。这一步如果跳过，下次新开终端会提示 command not found: brew，很多人就在这里卡住了。
Apple Silicon 芯片执行：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"Intel 芯片执行：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile eval "$(/usr/local/bin/brew shellenv)"简单解释下原理：brew 的安装目录不在系统默认的 PATH 里，系统找不到 brew 命令。第一条命令把一个初始化语句写进当前用户的 .zprofile 文件，这样每次打开新的 zsh 终端，都会自动加载这个路径；第二条命令让当前终端立刻生效，不用重启终端。
如果你用的是 bash 而非 zsh，把目标文件从 .zprofile 改成 .bash_profile（或 .zshrc 对应调整）也可以。验证是否配置成功，新开一个终端窗口执行 which brew，能看到 /opt/homebrew/bin/brew 或者 /usr/local/bin/brew 就算成功。
4.2 brew doctor 和 brew config 自检
装完 brew、配好 PATH 之后，我强烈建议先跑一次自检。执行 brew doctor，它会扫描整个环境，指出可能影响 brew 使用的问题。常见提示包括：命令行工具版本异常、某些目录权限不对、环境变量冲突等，绝大多数警告都有具体修复建议，照着提示执行即可。看到 “Your system is ready to brew” 就说明一切正常。
再执行 brew config，可以查看 brew 的详细配置信息。重点关注这几项：HOMEBREW_PREFIX 是安装前缀，HOMEBREW_CELLAR 是软件安装目录，HOMEBREW_BOTTLE_DOMAIN 是预编译包下载域名。如果你刚才设置了镜像源，这里能看到对应的镜像地址，确认配置生效。
这两条命令不是可有可无的形式主义。很多初次安装成功但后续使用报错的用户，问题往往出在环境不自检这一步。比如 PATH 里同时存在多个版本的 python 或 git，brew 装好的工具能不能被正确调用，brew doctor 会给出非常直接的建议。
4.3 安装后的持久换源与常见坑
安装过程中通过 export 设置镜像环境变量，只对当前终端生效。如果希望以后每次使用 brew 都默认走镜像源，可以把 export 语句写进 shell 配置文件的末尾。以 zsh 为例：
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"' >> ~/.zprofile echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"' >> ~/.zprofilebrew 本体仓库和 core 仓库也可以用 git remote 直接改。使用中科大镜像时：
git -C "$(brew --repo)" remote set-url origin https://mirrors.ustc.edu.cn/brew.git git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git需要留意的是，新版 brew 的 formula 索引主要通过 JSON API 获取，所以 HOMEBREW_API_DOMAIN 和 HOMEBREW_BOTTLE_DOMAIN 这两个变量更重要；core 仓库的 remote 在部分版本里甚至可以不同步，保持默认即可。如果误改了 remote，想恢复官方地址，把 remote set-url 里的地址换成 https://github.com/Homebrew/brew.git 和 https://github.com/Homebrew/homebrew-core.git 就行。
还有一个常见的坑：换源之后，如果 brew update 还是卡住，多半是之前“半成品”的 git 仓库状态不对。这时候进到仓库目录，比如 cd "$(brew --repo)"，执行 git status 看看状态，必要时先把仓库备份，再删掉重新 clone，效果比反复重试好很多。
5. 高频报错与排查技巧实录
5.1 网络类错误：curl、443、Connection refused
安装 brew 最常遇到的报错就是网络层失败。我看到最多的一种是：
curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused这行的含义是 curl 尝试连接 raw.githubusercontent.com 的 443 端口失败。在多数情况下，brew 安装脚本都需要从 GitHub 服务器拉取脚本或仓库，网络连通性不佳时就会出现这类错误。处理办法很简单：先确认网络能正常访问网页；然后按前面讲的方式，设置镜像源环境变量重新执行安装脚本；或者换一个网络环境再试。
另一种常见报错是 “RPC failed; curl 56 OpenSSL SSL_read: Connection was reset, errno 54”，一般出现在 clone brew 仓库的过程中。这种情况说明连接在传输阶段被中断，解决办法同样是换镜像源、重试。GitHub 仓库因为传输文件多、连接容易中断，镜像站做了一层中转，失败概率会明显降低。
有同学会反复试同一个方案，在一片区域反复“撞墙”。这时候请跳出“再试一次”的思维，直接切镜像源安装，效率高得多。
5.2 权限类错误：目录不可写、Operation not permitted
权限类报错是另一个高频问题。在 Intel Mac 上，brew 默认前缀是 /usr/local，而这个目录经常被系统强制保护，或者被之前手动安装的软件占用。执行安装脚本或 brew install 时，可能看到 Permission denied 或者 Operation not permitted。
一个常见修法是把目录所有权交给当前用户：
sudo mkdir -p /usr/local sudo chown -R "$(whoami)" /usr/localApple Silicon 上一般不需要处理 /usr/local 的权限，因为 brew 默认装在自己的 /opt/homebrew 目录里，这个目录安装脚本会自行创建并授权。如果在 Apple Silicon 上仍然遇到 /usr/local 相关问题，大多是之前手动创建的残留目录导致，确认没有重要文件后可以谨慎处理。
需要特别提醒：不推荐用 sudo chown -R 去改整个系统目录的属主，也不要随意 chmod 777。这会把系统文件权限搞得一团糟，后续可能出现更奇怪的问题。改权限的原则是“最小范围修复”，只处理 brew 需要写入的目录。
5.3 brew update 卡住的几种解法
brew update 卡住是装完后的日常问题。现象通常是执行 brew update 后长时间没有输出，或者一直停在某个 “Cloning” 阶段。原因大多是本地 git 仓库连接远端失败。解法有三个，从轻到重排列。
第一，临时关闭自动更新，使用 HOMEBREW_NO_AUTO_UPDATE=1 brew install 包名，先保证安装能用。第二，切换镜像 remote，让 update 从镜像仓库拉取索引，和前面讲到的持久换源一致。第三，如果本地仓库状态已经混乱，可以进入 brew 仓库目录（brew --repo）手动执行 git fetch 看具体报错，或者备份后删除仓库重新 clone。删除仓库不会影响已安装的软件，只是索引重新下载一次。
我的建议是：平时把镜像源配置好，brew update 基本不会再让你操心。每次执行 install 时，brew 默认会检查自动更新，这个检查在镜像源配置不当的情况下会变成等待的“黑洞”。很多用户觉得 brew 卡，其实是卡在自动更新上。熟悉后可以显式设置 HOMEBREW_NO_AUTO_UPDATE=1，再配合定期手动 brew update，体验会顺畅许多。
5.4 版本冲突：新装的工具调不起来
装完新工具却执行不了，是新手最容易懵的场景。比如系统自带 git 是 2.39，但你 brew install git 装了 2.47，执行 git --version 还是 2.39。原因很简单：系统自带的 git 路径在 /usr/bin/git，brew 装的在 /opt/homebrew/bin/git，而 PATH 变量里的搜索顺序是前者更靠前。
解决办法是调整 PATH 顺序，让 brew 目录排在更前面。如果你已经在 .zprofile 里写了 eval "$(/opt/homebrew/bin/brew shellenv)"，系统一般会自动把 /opt/homebrew/bin 放到 PATH 靠前位置。验证方式：执行 which git，看是否指向 /opt/homebrew/bin/git；如果不是，检查 .zprofile 是否被正确加载，或者手动在 .zshrc 里把 /opt/homebrew/bin 追加到 PATH 前面。
类似的冲突也会出现在 python、openssl 等工具上。这不算 bug，而是环境管理的一部分。理解 PATH 机制之后，你就能快速定位“为什么执行的可执行文件不是我以为的那个”。
6. 从安装到日常用：常用命令与实战场景
6.1 高频命令速查表
装好 brew 之后，日常使用其实就下面这些命令：
| 操作 | 命令 |
|---|---|
| 搜索软件包 | brew search 关键字 |
| 查看软件信息 | brew info 包名 |
| 安装命令行工具 | brew install 包名 |
| 安装图形应用 | brew install --cask 应用名 |
| 卸载软件 | brew uninstall 包名 |
| 查看已安装 | brew list |
| 更新 brew 本身 | brew update |
| 升级所有软件 | brew upgrade |
| 查看需要升级 | brew outdated |
| 清理旧版本 | brew cleanup |
| 管理后台服务 | brew services list/start/stop 服务名 |
这些命令不用死记，用多了自然熟。我通常会把 brew update 和 brew upgrade 放在一起说，因为 brew upgrade 升级的是已安装的软件包，brew update 更新的是索引本身，两者配合使用才能保证升级到最新版本。
6.2 常见开发工具安装实例
举几个实际安装例子，感受一下 brew 的效率。装 python 和 git：
brew install git python装 JDK（OpenJDK 17）：
brew install openjdk@17装 MySQL 数据库，并注册为后台服务：
brew install mysql brew services start mysql装 Maven、Node.js：
brew install maven node以上命令的下载和安装过程都是自动的。如果你之前配置好了镜像源，速度会非常可观。我个人的习惯是：先把 brew 装好，然后一条命令把 git、python、node、openjdk 这些基础环境全部装完，整个过程不超过十分钟。对于经常接触新工具的人来说，brew 还能帮你快速安装 jq、wget、tree、ripgrep 这类小而美的命令行工具，用 brew search 搜一下就能找到。
除了命令行工具，图形应用也可以通过 cask 安装。比如：
brew install --cask iterm2 brew install --cask visual-studio-code brew install --cask google-chromecask 会把应用安装到 /Applications 目录，和从官网下载拖入的效果一致，但好处是版本可追踪、更新更方便。
6.3 卸载与清理：给硬盘留点空间
brew 装得越多，对磁盘空间的占用也越大，尤其是老版本残留和编译中间产物。定期清理是保持环境健康的一部分。先看哪些包可以升级：brew outdated；然后升级：brew upgrade；卸载无用包：brew uninstall 包名；清理不再需要的依赖：brew autoremove；清理旧版本和临时文件：brew cleanup。
执行 brew cleanup 后，系统会删掉每个软件包的老版本文件，只保留当前版本。如果磁盘吃紧，这招通常能腾出不少空间。如果你彻底不想用 brew 了，官方也提供了卸载脚本：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"卸载脚本会询问你要删除哪些目录，确认后会把 brew 本体、仓库和由 brew 管理的软件目录一并清理。它会保留你手动安装的文件，但由 brew 管理的软件会消失，所以卸载前先想清楚，不要把重要数据放在这些目录里。
以我这些年的使用体验，brew 装上只是开始，真正让它发挥价值的是把你重复的操作沉淀成一条条命令。刚装完的新机器，环境整洁、镜像源配好，之后维护起来会省很多精力。还有一些小习惯值得培养：比如不要把 brew 目录的权限随意改大，也不要因为一次慢就反复重装。很多问题不是 brew 的锅，是网络和环境的问题。先检查连接，再考虑换源，基本能覆盖九成以上的麻烦。
最后分享一个我自己的习惯：每次在新 Mac 上装完 brew，第一件事不是装各种软件，而是先执行 brew doctor 确认环境干净，再把镜像源配置写进 shell 配置文件。之后再去 brew install 并顺手保存一份常用软件清单，方便以后重装机器直接批量恢复。这个方法我用了很多年，身边的朋友照着做之后，基本没有再被 brew 安装问题困扰过。
