解决 brew install 慢：换用清华镜像源

用 Homebrew 装软件时，下载卡住、速度极慢是常见问题。原因通常是默认源在国外，国内访问不稳定。笔者这里记录一个简单做法：把 Homebrew 的下载地址换成清华镜像，速度会明显改善。

01 | 为什么要换镜像

Homebrew 安装软件时，需要先访问 API 获取软件信息，再去下载对应的 Bottle 包。这两步默认都走国外地址，国内访问容易超时或龟速。其中 API 元数据体积较小，通常直连即可；真正占体积、拖慢速度的是 Bottle 二进制包。

把下载地址指向国内镜像，就能绕开网络瓶颈。清华 TUNA 镜像站提供了 Homebrew 的 Bottle 镜像，配置起来只需几条命令。

下面这张图概括了默认源与镜像源在安装流程上的差异：

flowchart LR subgraph Default["默认源（国外）"] A1[brew install] --> A2[访问 API 获取软件信息] A2 --> A3[下载 Bottle 二进制包] A3 -.国外地址.-> A4[易超时 / 龟速] end subgraph Mirror["配置 Bottle 镜像后"] B1[brew install] --> B2[访问 API 获取软件信息] B2 -.API 直连.-> B3[下载 Bottle 二进制包] B3 -.镜像地址.-> B4[走清华镜像加速] end Default ~~~ Mirror

02 | 配置镜像命令

打开终端，执行下面两条命令。以下命令针对 zsh（macOS Catalina 及以后版本的默认 shell），会把镜像地址写入 ~/.zshrc，让每次打开终端都自动生效。如果你使用的是 bash，请把 ~/.zshrc 换成 ~/.bash_profile（或 ~/.bashrc，取决于你的配置）。

echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc
source ~/.zshrc

第一条设置 Bottle 下载镜像地址，第二条让配置立即在当前终端生效。

这里只设置 HOMEBREW_BOTTLE_DOMAIN，不再设置 HOMEBREW_API_DOMAIN。原因是 Homebrew 4.0 之后引入了基于 API 的安装机制，而部分国内镜像站对 API 代理的支持会随时间和版本调整（具体以所用镜像站公告和 Homebrew 官方文档为准）。如果仍把 API 地址指向镜像，最新版 brew install 可能报 404 Not Found 或直接报错。API 元数据本身体积很小，直连即可；真正占体积、拖慢速度的是二进制大包，交给 Bottle 镜像加速就够了。

注意：这条命令使用 >> 追加写入，重复执行会在 ~/.zshrc 中留下重复行。如需再次执行，建议先检查文件中是否已存在这一行。

03 | 清理与验证

如果你之前已经写入过 HOMEBREW_API_DOMAIN 或重复的 HOMEBREW_BOTTLE_DOMAIN，建议先备份配置文件（例如执行 cp ~/.zshrc ~/.zshrc.bak），再清理：

# 以下命令仅适用于 macOS；其他系统请用 vi、nano 等编辑器打开 ~/.zshrc
open -e ~/.zshrc

在打开的编辑器中找到文件末尾，删除多余或重复的 export HOMEBREW_API_DOMAIN=... 和 export HOMEBREW_BOTTLE_DOMAIN=... 行，只保留一行：

export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

保存关闭后，在终端运行：

source ~/.zshrc

验证是否生效，可以执行：

echo $HOMEBREW_BOTTLE_DOMAIN

如果终端输出了 https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles，说明该环境变量已在当前终端生效。但这只代表变量已设置，并不等于 brew 一定使用了该镜像；如需确认，可运行 brew install 并观察安装过程中显示的下载地址或日志，确认下载 URL 是否指向清华镜像。

如果发现没有变化，可以先确认环境变量是否生效，再检查 ~/.zshrc 中是否已写入这一行，或者确认当前终端使用的是 zsh。该配置只是替换 Bottle 下载地址，对多数 Homebrew 版本适用，但环境变量名称和镜像可用性可能随版本或网络环境变化，请以所用 Homebrew 版本的官方文档和实际测试结果为准。

下面的流程图概括了从配置到验证的完整排查路径：

flowchart TD S[执行 brew install 慢] --> C[写入 HOMEBREW_BOTTLE_DOMAIN 到 ~/.zshrc] C --> R[source ~/.zshrc 使其生效] R --> V{echo $HOMEBREW_BOTTLE_DOMAIN} V -->|输出镜像地址| OK[配置生效，下载走清华镜像] V -->|无输出或不对| T1[检查 ~/.zshrc 是否已写入该行] T1 --> T2[确认当前终端是否为 zsh] T2 --> T3[检查是否残留 HOMEBREW_API_DOMAIN 或重复行] T3 --> R

关注我，和AI一起成长~