Homebrew完全指南：macOS包管理器安装配置与镜像加速实战

从新 Mac 开机到项目环境能跑起来，中间隔着的往往不是代码，而是一堆“缺这个库、少那个依赖”的破事。我第一次被 Homebrew 圈粉，是在一台刚拆封的 MacBook 上想装 Git：去官网下 dmg、拖进 Applications、打开又提示缺证书、最后还得自己配 PATH，折腾了一上午。后来朋友甩过来一句话：先装 Homebrew，后面所有软件一条命令搞定。从此我再没手动编译过那些开源工具。

Homebrew 是 macOS（也支持 Linux）上的包管理器。它解决的核心问题，是把所有命令行软件和常见 GUI 软件的安装、升级、卸载、依赖管理统一成 brew install、brew upgrade、brew uninstall 这样的命令。不管你是刚接触 Mac 的新手，还是已经踩过无数坑的开发者，它基本是进入 macOS 开发环境的第一块基石。下面这篇很长，我按“为什么需要它、怎么快速装好、日常怎么用、遇到问题怎么排”四个角度展开，全部来自我这几年的实机操作，不是贴文档。先从不废话开始。

1. Homebrew 到底解决了什么问题，为什么 macOS 用户绕不开它

1.1 包管理器的价值：从“手动装软件”到“一句话搞定”

在说 Homebrew 之前，先看没有它的时候我们是怎么装软件的。很多开源工具，比如 ffmpeg、wget、nginx、mysql，并不会给你一个干净的 dmg 安装包。你通常要去 GitHub 下载源码，然后自己执行 configure、make、make install。听起来不难，但一旦某个工具依赖几十个子库，比如编译 OpenSSL 需要 perl，编译 perl 又需要一堆头文件，你就陷入“装 A 要先装 B，装 B 又要先处理 C”的依赖地狱。

Homebrew 的价值在于，它把“安装某个软件”这件事抽象成一份配方，官方叫 formula。每个 formula 里写清楚了这个软件的下载地址、依赖清单、编译参数、安装目录。你执行 brew install ffmpeg，Homebrew 会自动把依赖列表里的所有包按顺序装好，最后把 ffmpeg 本身放到位。整个过程不需要你手动管理中间步骤，出问题也能通过提示快速定位。

另外一个容易忽略的好处是可卸载性。手动编译安装的软件，通常要散落在 /usr/local/bin、/usr/local/lib、/usr/local/etc 好几个目录。想卸载？你根本不知道哪些文件是它的。Homebrew 把所有东西集中放在 Cellar 目录，用一个软链接机制暴露到系统路径。卸载时执行 brew uninstall 包名，它把本体和依赖关系清理掉，不会留下乱七八糟的残留。

对于国内用户来说，Homebrew 还有一个极其重要的角色：很多命令行工具在国内下载慢、版本老、或者根本没有官方 Mac 安装包，而 Homebrew 的镜像源体系能比较统一地解决“去哪里下载、下载哪个版本、装到哪个路径”的问题。后面第 2 节我会专门讲镜像加速，这是能不能顺利使用的关键。

1.2 先记住这些高频概念，后面才不会懵

用 Homebrew 的时候，你会反复看到 formula、cask、tap、cellar、bottle 这些词。我刚开始也分不清，后来按自己的理解整理成了下面这张表：

这里最需要区分的是 formula 和 cask。简单说，brew install git 安装的是命令行工具，走 formula；brew install --cask chrome 安装的是图形界面软件，走 cask。这个区分很多人第一次接触时容易搞混。尤其是刚从各种教程里复制命令时，发现 brew install --cask firefox 能装浏览器，而 brew install firefox 会报“找不到且不会从 cask 自动匹配”。请记住：从 Homebrew 3.0 开始，安装 GUI 应用必须显式加 --cask。

Tap 在安装第三方工具时非常常见。默认源里的软件可能不全，某个工具只在作者自己的仓库里有。这时候你就得 brew tap 作者名/仓库名，把那个仓库添加进来，之后才能安装其中的软件。这个机制会反复用到，尤其在第 4 章讲 codex 这类非默认源工具时。

2. 手把手安装 Homebrew：环境检查、镜像加速与首次自检

2.1 开始之前：确认系统与基础工具

在 Mac 上安装任何开发环境，第一步永远是先搞清楚自己机器的底细。Homebrew 的安装路径和系统架构强相关。

先跑一句：

bash复制uname -m

如果输出 arm64，说明是 Apple Silicon 芯片（M 系列），Homebrew 会装在 /opt/homebrew 目录。如果输出 x86_64，说明是 Intel 芯片，或者你在 Apple Silicon 上用 Rosetta 模拟 x86 环境，Homebrew 会装在 /usr/local 目录。建议所有 M 系列用户优先使用 arm64 原生的终端，不要去用 Rosetta 终端的 x86 Homebrew，否则后续装包架构混乱会很麻烦。

另外要确认你已经装了 Xcode Command Line Tools。没装时，终端里运行 git 会弹窗提示安装，也可以主动执行：

bash复制xcode-select --install

这一步是 Homebrew 能正常编译、链接软件的基础。虽然 Homebrew 本身不依赖完整 Xcode，但很多工具编译时会调用 clang、make、git 这些命令行工具，它们都在 Command Line Tools 里。

2.2 安装为什么慢或卡住？镜像加速的原理与配置

Homebrew 官方安装脚本本身不长，核心动作是：从 GitHub 拉取 Homebrew/brew 仓库到本地，然后执行内置的安装逻辑。真正慢的地方在后面，你按官方一条命令：

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

这里的下载地址大多指向境外服务器。在我实测的网络环境下，可能会出现三种现象：第一，install.sh 半天下载不下来；第二，下载下来了，但 clone brew 仓库时卡在 remote: Enumerating objects 很久；第三，首次 brew update 或安装某个包时，从 GitHub Releases 下载二进制的速度极慢。

解决办法很简单：用国内的镜像源，比如清华开源镜像站、中科大开源镜像站。这不是把 Homebrew 功能改掉，只是让 Homebrew 从“去境外下载”变成“从境内镜像下载”，其余逻辑完全不变。

镜像加速的原理分两块。Homebrew 4.0 以后的版本，默认通过 GitHub API 获取 formula 信息，不再依赖本地维护一个完整的 homebrew-core git 仓库。所以你要把三个“出口”都指到镜像：

• HOMEBREW_BREW_GIT_REMOTE：指定 brew 本体仓库的地址
• HOMEBREW_CORE_GIT_REMOTE：指定 core 仓库的 git 地址（旧版本或手动 clone 时需要）
• HOMEBREW_API_DOMAIN：指定 formula 元数据 API 的镜像地址
• HOMEBREW_BOTTLE_DOMAIN：指定预编译二进制包的镜像地址

这四项配置好之后，不管是 git clone 还是下载 bottle，都会走镜像站点，速度能提升几个数量级。

2.3 完整安装过程（以国内镜像为例）

下面是我自己在新 Mac 上实测过的一套流程，以清华镜像为例。

先打开终端，把环境变量配置好：

bash复制export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

然后下载官方安装脚本执行：

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

脚本运行过程中会创建 /opt/homebrew 目录（Apple Silicon）或使用 /usr/local（Intel），并把 brew 本体 clone 到对应路径。环境变量已经指到了清华，所以 clone 速度通常很快。如果 install.sh 本身下载超时，可以先单独下载到本地再执行：

bash复制curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o install.sh
bash install.sh

这一步建议用普通用户执行，不要加 sudo。Homebrew 设计上允许普通用户管理自己的目录，最多会在某些系统操作需要权限时提示输入密码。如果整个安装过程在 sudo 下执行，后面会产生一堆属主为 root 的文件，导致各种 permission denied 问题。

安装完成后，终端会提示你把 Homebrew 的 shell 环境写入配置文件。Apple Silicon 的默认 shell 配置文件是 ~/.zprofile，Intel Mac 同样建议写 ~/.zprofile。按提示执行：

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

再执行 brew --version，看到版本号说明安装成功。

2.4 安装完成后的自检

我习惯在安装完 Homebrew 后先跑一遍检查，而不是急着装软件。

bash复制brew doctor

这个命令会检查当前环境有没有潜在问题。常见的输出包括：

• “Your system is ready to brew”：没问题
• 提示有旧版配置或警告：按提示处理即可
• 提示某条 PATH 路径顺序不对：用 echo $PATH 查看 /opt/homebrew/bin 是否在 /usr/local/bin 前面

还需要确认镜像配置是否真的写进去了。执行：

bash复制echo $HOMEBREW_BOTTLE_DOMAIN

如果输出为空，说明上面的环境变量只对之前那次终端会话有效，新开窗口又没了。我建议把配置永久写进 shell 配置文件：

bash复制echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zprofile
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zprofile
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zprofile
source ~/.zprofile

注意：HOMEBREW_BREW_GIT_REMOTE 和 HOMEBREW_CORE_GIT_REMOTE 并不一定每个用户都需要写进配置文件。如果你平时不手动 clone 官方源码，只靠默认 API 走镜像，写前三个对大部分场景就够用了。我之所以把四个都写上，是为了兼容某些旧版本工具和第三方 tap 里仍然走 git clone 的安装方式。

最后可以装个小软件看整体链路是否通：

bash复制brew install wget

如果能在几十秒内完成，说明 git 拉取、API 获取、bottle 下载都走通了，后面使用会很顺畅。

3. Homebrew 基本操作：查询、安装、更新与日常维护

3.1 常用命令速查表

Homebrew 日常用到的命令其实不超过十个。我给团队做内部分享的时候，会先让大家把下面这张表抄一遍：

我建议新手先记住 search、info、install、uninstall、upgrade 这五个。其他用到再查。

3.2 命令行工具与图形应用（Cask）的差异

日常最容易混的一个操作，是我前面提到过的 cask。当你搜某个软件时，输出结果里可能会同时出现 formula 和 cask，两者并不是替代关系。

举个例子，我搜索 firefox：

bash复制brew search firefox

结果会同时告诉你 firefox 并没有 command line formula，但有 cask 版本的 firefox。Linux 下有 firefox 的发行包，macOS 上你用 brew 装 Firefox 就必须写成：

bash复制brew install --cask firefox

同样地，装 VS Code：

bash复制brew install --cask visual-studio-code

而像 git、python、node、ffmpeg 这些，默认只存在于 formula 仓库。

为什么会分两套？因为命令行工具的安装逻辑是把可执行文件放进统一目录，再创建软链接；GUI 应用则是把整个 .app 包拖入 /Applications，两者文件结构完全不同。Homebrew 把它们拆成 formula 和 cask 两套标签，管理起来更干净。卸载时也一样，brew uninstall --cask firefox 会把应用从 /Applications 移除，但通常不会删除你个人的用户配置，比如浏览器的书签和插件，这个特性要记住，不然重装系统时容易误删数据。

3.3 更新、升级、清理的正确姿势

很多人的 Homebrew 用久了会越来越慢，一个重要原因是安装的包太多、旧版本太多、缓存太大。定期做清理是保持健康的关键。

我推荐一套节奏：

bash复制brew update
brew outdated

先看有多少包能升级。然后决定是全量升还是挑重点升。生产环境机器我不建议无脑 brew upgrade，因为升级所有包可能引入不兼容的新版本，比如项目依赖 Python 3.10，结果全量升级把 Python 升到 3.12，代码直接跑不起来。更稳的做法是：

bash复制brew upgrade 具体包名

按需升级。

定期执行：

bash复制brew cleanup -n

-n 表示 dry run，只是预览会清理哪些旧版本和缓存，不会真正删。确认没问题后去掉 -n 执行一次，能把磁盘占用降下来不少。

还有一个易踩的坑：当某个软件被卸载后，它的依赖并不会自动跟着删。时间长了，系统里会堆积大量没有被任何软件引用的孤立依赖。可以用：

bash复制brew autoremove

清理它们。不过执行前最好看一眼它准备删什么，我遇到过把某个其他软件还在用的共享库当作孤立依赖删掉的情况，虽然概率不高，但稳妥起见先 brew autoremove --dry-run 比较靠谱。

3.4 服务类软件管理

Homebrew 装完 mysql、nginx、redis 这类常驻服务后，有时会希望它在后台自动运行。一个常见错误是直接用 brew install mysql 然后以为它已经启动了。实际上它只是装好了文件，并没有启动。

Homebrew 提供了 services 子命令：

bash复制brew services list
brew services start mysql
brew services stop nginx
brew services restart mysql

list 可以看到每个已安装服务当前是否在运行。start 之后服务会注册为后台进程，即使你关掉终端也会继续跑。如果不小心手滑启动了一个不需要的服务，可以用 stop 停止；想卸载并取消自启，先 brew services stop 服务名，再 brew uninstall 服务名。

把这个命令记住，能省掉很多“为什么装好了却连不上”的排查时间。

4. 高频 FAQ 排查实录：从报错到卸载残留

4.1 Xcode Command Line Tools 相关的常见报错

我见过最多的异常，不是 Homebrew 本身坏了，而是 Command Line Tools 状态不对。一类典型错误长这样：

bash复制xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun

或者：

bash复制xcode-select: error: tool 'xcodebuild' requires Xcode

出现这类提示，说明系统中找不到可用的开发命令行工具，或者 xcode-select 指向的路径已经失效。常见的触发原因是系统升级后 Command Line Tools 版本与系统不完全匹配，或者你手动删除了 /Library/Developer/CommandLineTools 目录。

处理办法：

bash复制xcode-select --install

如果已经安装但仍然报错，可以重置路径：

bash复制sudo xcode-select --reset

还有一种是安装了完整 Xcode 后没有同意许可协议，编译时报错会让你执行 sudo xcodebuild -license accept。这种通常发生在你从 App Store 安装或更新了 Xcode 之后。

4.2 brew update / install 网络问题的逐项排查

关于网络，我需要谨慎但又实用地讲清楚。Homebrew 大量资源来自境外 GitHub，很多用户遇到的“卡死”，本质是网络环境访问境外服务器速度很差，而非命令写错。合规且安全的方案就是使用国内镜像源。

如果 brew update 明显卡住，第一个动作是确认环境变量是否已生效：

bash复制echo $HOMEBREW_API_DOMAIN
echo $HOMEBREW_BOTTLE_DOMAIN

如果为空，按第 2 节的方法把镜像配置写入 shell 配置文件。然后执行：

bash复制brew update --verbose

看看它到底卡在哪一步。如果卡在 brew 本体的 git pull，检查：

bash复制cd "$(brew --repo)"
git remote -v

输出应该指向清华或其他镜像站的 brew.git。如果还是官方 GitHub 地址，就手动替换：

bash复制git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

完成后再 brew update。

另一个常见现象是执行 brew install 包名 的时候，前面在下载 bottle，进度条一动不动。这种大多是因为 bottle 默认从 ghcr.io 下载，而你没有配置 HOMEBREW_BOTTLE_DOMAIN。设好镜像域后，重新执行即可。

还有一个体验优化项：如果你不希望每次运行命令前都自动执行 brew update，可以按需关掉：

bash复制export HOMEBREW_NO_AUTO_UPDATE=1

但这个环境变量建议只在特定终端会话临时设置，不要默认全局关闭，否则你会错失很多 formula 的最新安全更新。

4.3 brew install 校验失败或缓存损坏

安装过程中如果出现这种输出：

bash复制Error: Checksum mismatch.
Error: Failed to install ... 

大概率是下载的二进制不完整，或者本地缓存了坏文件。这种情况不用急着换镜像站，先把缓存清掉再试：

bash复制rm -rf "$(brew --cache)"
brew cleanup
brew install 包名

$(brew --cache) 会展开为 Homebrew 的下载缓存目录，一般在 ~/Library/Caches/Homebrew/downloads。里面有很多按哈希命名的文件，手动清理容易误删正在使用的缓存，直接用命令删更安全。清掉后重新下载，通常能解决。

如果反复出现校验失败，也可能是镜像源上的 bottle 与你本机系统版本不完全匹配。macOS 大版本刚发布时，部分 bottle 还没跟上，Homebrew 会尝试从源码编译安装，编译时又可能因为缺少依赖而出错。这时候brew info 包名看它有没有适用于当前系统的二进制包，最省事的办法是等官方或镜像跟上后重试，或者用 brew install 包名 --build-from-source 源码编译顶一下。

4.4 卸载残留：官方卸载后还要手动清理什么

要卸载 Homebrew 并不是“关掉终端”或“删掉 /opt/homebrew 文件夹”那么轻巧。官方卸载脚本：

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

执行后确实能移除主要文件，但我在实际操作中发现，它并不会把所有配置、缓存、遗留软链接都清掉。手动检查时要注意下面几类残留：

第一类是主安装目录相关文件。Apple Silicon 上主要是 /opt/homebrew，Intel 上主要是 /usr/local/Homebrew、/usr/local/Cellar、/usr/local/Caskroom。官方卸载脚本会处理大部分，但如果有权限异常的文件没删干净，可以手动补：

bash复制sudo rm -rf /opt/homebrew

这条命令在 Intel Mac 上要格外小心，不要直接删整个 /usr/local，那里面可能还有你自己装的系统级软件。

第二类是用户目录下的缓存与支持文件：

bash复制rm -rf ~/Library/Caches/Homebrew
rm -rf ~/Library/Application\ Support/Homebrew

前者体积通常很大，装着各种下载过的包体。后者包含一些 Homebrew 运行时产生的配置。

第三类是 shell 配置文件里的环境变量和 PATH 设置。前面安装时我们往 ~/.zprofile（或 ~/.bash_profile）里写了 eval "$(/opt/homebrew/bin/brew shellenv)" 和几个 HOMEBREW_* 导出语句。卸载后如果不删掉，每次打开终端都会看到类似 command not found: brew 的报错。手动编辑这个文件，删除对应行即可。这一步网上很多教程都没提醒，是卸载后“总觉得哪里不对”的主要来源。

第四类是其他软件里的引用。如果你用 VS Code、JetBrains 等工具配置过 Homebrew 的自动补全，卸载后相关路径还留在配置里，虽然不是大问题，但排查怪异报错时记得回溯到这里。

特别提醒：不要为了“清理干净”而去删除 /usr/local/bin 下的全部软链接。很多 Mac 用户自己手动安装过其他软件，也可能在里面放了可执行文件。正确做法是只删除指向 /opt/homebrew 或 /usr/local/Cellar 的失效链接，可以用：

bash复制ls -la /usr/local/bin | grep "Cellar\|homebrew"

逐条判断后再删。

4.5 用 Homebrew 安装搜索不到的第三方命令，以 codex 场景为例

很多人遇到一个问题：我想装某款工具，但 brew search 搜不到，是不是 Homebrew 不支持？不一定是，很可能它不在默认仓库里，需要通过 tap 添加第三方源后安装。

以我近期帮同事解决的 codex 命令行工具场景为例。先执行：

bash复制brew search codex

如果默认源里存在，直接 brew install codex 就可以。如果搜不到，就去工具官网或 GitHub 仓库看它推荐的安装方式。很多现代 CLI 工具会维护自己的 Homebrew tap，官网通常会给出类似下面这样的安装说明：

bash复制brew tap 某组织/homebrew-tap
brew install 某组织/homebrew-tap/codex

这里的 某组织 是具体仓库的作者名，每个工具都不一样，以官方文档为准。为什么是这样的结构？因为 tap 的本质就是把一个独立的 git 仓库挂到 Homebrew 的源列表里，仓库里写好了 formula，之后 Homebrew 就能找到并安装它。

在执行 tap 之前的注意事项：绝对不要随手添加来路不明的 tap。第三方仓库里的 formula 可能安装脚本会向系统写入额外内容，安全性没有官方仓库那种背书。我会随手去 GitHub 上看一眼仓库的 star 数、更新时间、代码内容，再决定是否信任。比较稳妥的办法是优先找官方项目主页链接过去的 tap 仓库，而不是搜索引擎里随手翻到的“分享源”。

如果目标工具不是 CLI，而是 GUI 应用，那搜索方向就应该变成 brew search --cask codex。搜索结果没有时，一般说明它的开发者没有打包 cask，社区也没有人维护，这种情况只能去官网下载 dmg 或 pkg 安装。

4.6 两个很容易忽略但破坏力很大的误操作

最后想专门提醒两个容易“手滑”的操作。

第一个是直接删 /opt/homebrew 里的文件来“修复”问题。Homebrew 的文件结构是按 keg 组织的，某个包安装后会在多个目录留下软链接，比如 /opt/homebrew/opt/xxx、/opt/homebrew/bin/xxx。当你发现某命令有问题，盲目删掉对应的可执行文件，往往会让 brew 内部状态错乱，甚至导致后续 brew uninstall 都无法正常执行。遇到这种情况，应该用卸载命令而不是手动删文件。如果手动删了，让 brew 意识到状态不一致的办法通常是：

bash复制brew doctor

并按它的提示执行 brew prune 或重装相关包。

第二个是频繁更换镜像源。有些用户觉得某个源慢了就立刻换另一个，换的过程中又只改了 HOMEBREW_BOTTLE_DOMAIN，没改其他环境变量，导致 brew 的下载源和 API 源来自不同镜像站，会出现数据不一致的诡异问题。我自己的做法是：认准一个源，把环境变量一次性写全，除非长时间速度无法接受，否则不要频繁切换。镜像源服务也可能有暂时不稳定的情况，偶尔慢一下不代表它失效，先排查网络和缓存，再来考虑是否换源。

5. 我沉淀下来的几个 Homebrew 使用习惯

这篇文章写了这么多，最后分享几条我实际维护几台 Mac 之后沉淀下来的习惯，供你参考。

第一，新机器装完 Homebrew 后，我会立刻固定一份“初始安装清单”，包含 git、wget、zsh-completions、jq、tree、ripgrep 这类日常高频工具。一次性装完，比以后想到一个装一个更省心。第二，我不会在关键工作目录里频繁执行全局 brew upgrade。先看 brew outdated，再按项目需求单独升级，能避免很多无谓的版本破坏。第三，每个月我会跑一遍 brew doctor 和 brew cleanup，顺手把日志里的 warning 消除掉。这个过程就像定期打扫房间，不费多少时间，但能防止问题累积。

还要强调一点：Homebrew 是装在系统里的包管理器，不是某个项目的虚拟环境。系统级软件一旦升级，影响是全局的。如果你在同时维护复杂项目，建议把项目级的运行时依赖尽量交给 pyenv、nvm、rbenv 这类版本管理工具，Homebrew 只负责提供这些工具本身的底层软件，以及一些系统级命令行工具。

Homebrew 本身也是一个活跃更新中的项目，官方文档和镜像站的说明会在你遇到新问题后给出最新的解决办法。这篇写到的命令都是我这几年里反复跑过的，大多数情况都能直接用。希望你在自己的 Mac 上少走点弯路。