Homebrew在Mac上几乎成了开发者的标配，装个nginx、wget、ffmpeg都得靠它。但有个问题大家迟早会遇到：brew install啥都挺顺，偏偏卡在Updating Homebrew和fetching的环节上，一卡就是十几分钟，最后还可能直接报错失败。这事的根源并不复杂——brew的仓库和下载地址都指向官方托管平台，国内网络访问速度实在不稳定，所以换源就成了几乎所有国内Mac开发者都要做的一步操作。
这篇文章我把我实际换源的整个思路和操作过程完整写下来，包括为什么慢、源怎么选、具体命令怎么敲、换完之后常见的坑怎么排查，一次性讲清楚。适合刚接触brew的新手，也适合已经换过源但遇到奇怪问题的朋友对照查漏。
1. 为什么你的brew这么慢：慢的三个环节逐一拆解
1.1 brew到底在下载什么：它不是一个单一的程序
很多人的直觉是brew就是一个安装工具，慢就慢在下载软件包本身。实际上brew的慢往往不是慢在包下载，而是慢在另外几个你平时注意不到的环节。
brew的运行可以拆成三个相对独立的组成部分：一是brew命令行工具本体，它本身是一个Git仓库；二是软件包描述仓库（打包了各类软件安装规则），早期叫homebrew-core，后来精简为API列表；三是预编译二进制包（bottles），这才是真正下载安装的软件包。
以安装nginx为例，brew首先需要从远程仓库获取nginx这个软件包的定义信息，然后根据定义里写的下载地址去拉取预编译好的二进制包，最后执行一系列安装脚本完成部署。中间的仓库同步、软件信息获取、二进制包下载，每一步都在访问网络，而这三个环节恰好都依赖官方托管环境。换算成吃饭的场景，就是你点了个外卖，商家、骑手、平台都是远距离通信，任何一个环节信号差，整单都会卡住。
1.2 网络路径上的三个瓶颈
先说Git仓库同步的问题。brew本身和旧版本的软件包描述仓库都是以Git仓库形式存在的，每次你执行brew update，实际上是在做一次git pull，把这个仓库的最新记录从官方托管平台拉到本地。这个仓库的体积不小，加上国内访问官方托管平台时跨海链路质量不稳定、SSL握手的延迟很高，经常出现连接超时或者下载到一半断掉的情况。
再说API请求的问题。较新版本的brew为了提速，软件包信息不再依赖本地克隆庞大的描述仓库，而是改成了定期从官方API接口拉取JSON数据。这个改动本地少拉了很多仓库数据，但API请求依然发往官方托管平台，而官方API对单IP的请求频率有限额，一旦超出限额就会直接返回错误，报错信息通常是API rate limit exceeded，碰到这个问题很多人第一反应是网络断了，其实是被限流了。
最后才是bottles二进制包的下载。这类包托管在官方容器镜像仓库上，走的是另一套CDN链路，国内访问时DNS解析经常被污染，解析出来的节点延迟极高，下载速度有时候只有几十KB，装个大一点的软件包等到怀疑人生。
1.3 换源的底层原理：把地址都换掉
理解了上面三个瓶颈，换源的思路就很清晰了。换源要做的事情无非是两件：把brew相关的Git仓库地址从官方托管平台改成国内镜像站提供的地址；再把二进制包的下载环境变量指向国内镜像站的bottles目录。同步地，还需要把API请求地址也指向镜像站，避免请求频率限制的问题。
有一个细节常被忽略：镜像站的仓库目录结构和官方平台不完全一样，但Git的remote机制允许你直接替换仓库地址，只要替换后的地址能正常访问、仓库内容是同步过的，本地就能继续正常拉取。git remote set-url这个命令就是干这个的。理解了这个原理，哪怕镜像站哪天地址变了，你也能自己重新换一遍，而不是只能照着教程抄。
2. 镜像源怎么选：用之前先看完这张对比
2.1 两类常见的国内镜像源
目前能用的国内镜像源基本分成两类。一类是高校开源镜像站，由各高校的互联网中心或者学生组织维护，特点是同步频率高、带宽充裕、完全免费，而且通常同时提供brew的仓库镜像和bottles镜像。另一类是云厂商镜像站，由商业云服务商维护，稳定性和访问速度都很可靠，同样免费开放。
两类我都实际用过。高校镜像站通常同步延迟更低，因为它们和上游的同步链路短，软件发布后几分钟就能在镜像站看到。云厂商镜像站的访问质量更均衡，机械硬盘还是固态硬盘的差异不大，它在骨干网上的接入位置好，晚高峰时段的表现通常比高校源更稳定。但要说明，这只是一般规律，每个镜像源的实际表现随地区和时段不同会有变化。
2.2 我的选型建议
我个人的建议是：优先选一个能正常打开、更新速度快的镜像源，而不是纠结哪个最好。换源本身成本很低，不满意随时可以再换，关键是先解决当前卡死的问题。
判断一个镜像源是否可用，最简单的办法是在浏览器里直接访问它的说明页，看是否有brew相关目录，再实际执行一次brew update观察速度。另一个经验是看镜像站是否同时提供bottles下载服务，因为Git仓库换源只能解决更新卡顿，bottles下载没换的话，安装大型软件时还是会从官方源硬拉，等于只解决了一半问题。建议选择同时提供这三类服务的镜像源：brew仓库、软件包信息、bottles二进制下载。
还有一个容易踩的坑：不同镜像源的仓库文件覆盖节奏不完全一致，如果你同时用甲镜像站的仓库、乙镜像站的bottles，某些软件的依赖校验可能出现版本不匹配。我在实际操作中的做法是认准同一个镜像站，把它的仓库和bottles都配上，避免混用。
3. 换源实操：从检查旧配置到完成替换
3.1 动手前先检查自己的环境
不要一上来就复制粘贴，先弄清楚两个前提。第一，你的Mac芯片架构是什么。Apple Silicon和Intel芯片的brew默认安装路径不同，但remote配置操作是通用的，你只要按照后面的命令跑就行。第二，你现在本地的brew远端地址是什么。执行一下：
brew --repo这个命令会输出brew本体的本地路径。确认路径后，查看当前的remote地址：
git -C "$(brew --repo)" remote -v正常情况下你会看到类似https://github.com/Homebrew/brew.git这种地址。如果这里显示的已经是一些国内镜像地址，说明你之前可能已经换过一部分源了，剩下的就是补齐缺失的部分。没有显示任何remote信息的话，说明仓库配置比较特殊，建议先重新设置remote，再继续后面的步骤。
动手之前我还建议你把当前远端地址抄下来存到文本里，万一换完出了问题，可以用同样的命令改回官方地址，这是最基本的备份思路。
3.2 替换brew本体仓库
第一步替换的是brew命令工具本身所在的仓库。执行：
git -C "$(brew --repo)" remote set-url origin https://镜像站地址/git/brew.git这里把https://镜像站地址/git/brew.git替换成你选定镜像站的brew仓库地址，不同镜像站的路径结构可能不同，有的在/git/brew.git，有的在/brew.git，以镜像站文档为准。
为什么先换这个仓库？因为后面所有操作都依赖brew命令本身，如果brew本科拉取不了，其他什么都跑不动。换完之后可以先试一下：
git -C "$(brew --repo)" fetch这个命令只是拉取远程的更新记录，不动你本地的仓库内容，适合用来验证网络通不通。如果这个命令能顺利执行完成，说明brew本体的换源已经成功了。
3.3 处理软件包描述仓库和API地址
接下来这一步要看你使用的brew版本，区别很大。
如果是较老版本的brew，软件包信息完全依赖本地克隆homebrew-core仓库，你需要逐一把相关仓库的remote换成镜像源地址。如果是较新版本的brew，本地不再保存完整的描述仓库，而是通过API请求获取软件包信息。这种情况下，你主要需要配置环境变量，让brew去请求镜像站提供的API地址，而不是官方地址。
拉取软件包信息的API地址需要单独设置环境变量，以你常用的Shell配置文件为基础。先确认你用的是zsh还是bash，绝大多数macOS用户使用的是zsh，配置文件是~/.zshrc。在文件末尾追加一行：
export HOMEBREW_API_DOMAIN="https://镜像站API地址"保存并执行source ~/.zshrc，让新环境变量在当前会话里生效。然后跑一次：
brew update如果输出显示从镜像地址正常拉取更新信息，说明配置成功了。这一步容易忽略的地方在于：很多人只换了Git仓库的remote，但brew逻辑已经改走API，结果你换了remote根本不生效，更新时照样访问官方地址。所以新版本brew一定要确认API环境变量配置到位。
3.4 配置bottles下载地址
仓库和API都指向国内之后，最后剩下的就是真正的软件包下载地址。bottles的下载地址通过HOMEBREW_BOTTLE_DOMAIN这个环境变量来配置。同样在你常用的Shell配置文件里追加：
export HOMEBREW_BOTTLE_DOMAIN="https://镜像站bottles地址"镜像站的bottles目录通常会区分不同Mac架构的包，但地址规则一般已经在环境变量里封装好了，你填的应该是镜像站文档给出的完整基础地址，不需要自己拼架构路径。
配置完成后，同样执行source ~/.zshrc让它生效。这里有一点要特别提醒：如果你之前已经安装过一些软件包，仓库里存在旧的bottle缓存，换了镜像源后brew检测到本地有对应缓存可能会直接使用旧缓存，你感觉不到下载速度已经变了。为了验证新配置确实生效，建议先清掉缓存再安装一个新包：
brew cleanup --prune=all然后随便挑一个软件包安装，比如：
brew install wget安装过程中观察下载地址，应该显示的是镜像站的地址。如果仍然显示官方地址，说明环境变量没被brew读取到，或者Shell配置顺序有问题。
3.5 补充配置：临时关掉自动更新
有一个配置我建议顺手加上，尤其网络状况一般的时候。brew在执行某些操作之前会自动触发更新检查，这个检查可能每次都会卡很久。虽然换源后更新速度已经大幅改善，但如果你只是在安装某个软件，根本不想等它更新，可以在配置文件里追加：
export HOMEBREW_NO_AUTO_UPDATE=1这个环境变量会让brew在安装、卸载等操作时跳过自动更新，只有你主动执行brew update时才会去更新。代价是你需要自己记得定期更新，不过实际操作中，按需更新的体验远好于每次安装都被强制检查。
4. 换源之后的常见问题和避坑
4.1 校验失败和下载中断
换源后装包最常见的报错是Checksum mismatch，意思是下载下来的文件校验值对不上。原因有两个：一是下载过程被中断导致文件不完整，二是镜像站同步上游的bottles文件还处于不完整状态。排查思路很简单，先删掉本地缓存，重新拉一次：
rm -rf "$(brew --cache)" brew install 软件包名如果重新下载后校验依然失败，很可能是镜像站本身同步有问题，这时可以临时切回bottles官方地址下载这一个包，或者换一个镜像源。不要每次都硬删缓存重试，浪费时间的概率大于解决的概率。
4.2 请求频率限制
配置好API地址后，如果你在短时间内频繁执行brew search、brew info这类查询命令，还是有可能会遇到限流问题，就算走的是镜像站也一样。原因是每个代理出口IP共享同一个请求配额。遇到限流，最直接的方法就是等几分钟再操作，另外可以避免频繁搜索软件。日常使用完全不会触发，只有手动排查时容易连续执行多条查询命令，注意控制节奏即可。
4.3 个别软件仍然下载很慢
换完源之后有个情况容易让人困惑：明明brew更新和大部分软件都走得很快了，为什么偏偏有个别软件还是慢如蜗牛？
我在实际使用中遇到过两类特例。第一类是软件包定义里写明了resource资源下载地址，这些资源是软件编译或运行需要的附属文件，地址写死在软件包定义里，不经过bottles下载，所以换源对它们没有影响。这类文件如果下载失败，只能等网络状况好的时候重试，或者看镜像站是否提供了额外的资源代理地址。第二类是cask型软件包，这类包下载的是应用安装程序的直接链接，有些链接指向境外厂商服务器，同样不受brew源控制。这种情况没有一劳永逸的解决办法，我的建议是遇到真正装不动的应用，单独搜索该应用的国内下载渠道。
4.4 如何彻底恢复官方源
换源操作是可逆的，恢复官方源只需要把之前改过的地址全部改回官方地址，并删掉对应的环境变量配置。
Git仓库的remote用同样的命令改回：
git -C "$(brew --repo)" remote set-url origin https://官方brew仓库地址Shell配置文件里把HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN两行删掉，保留HOMEBREW_NO_AUTO_UPDATE不影响源地址，继续保留也行。删完之后重新打开一个终端窗口，跑一遍brew update确认能够正常访问官方地址即可。恢复官方源之后建议顺手清一次缓存，避免本地残留的镜像站地址缓存干扰后续下载。
4.5 换源后的几条实操心得
第一个心得是环境变量配置完成后不要忘记新开终端窗口。很多人source完之后在当前窗口测试一切正常，结果下次打开新终端发现配置失效了，这是因为Shell配置文件的加载发生在终端启动时，而不是每一条命令执行时。如果确认配置没问题但新终端不生效，检查一下是否写错了配置文件，比如用的是zsh却写进了bash的配置里。
第二个心得是镜像站同步状态可以通过对比时间戳判断。执行完brew update后，如果提示的仓库更新时间比镜像站文档给出的同步时间晚很多，说明镜像站最近同步不正常，这是暂时性的，过几个小时再试大概率恢复。
第三个心得是不要频繁更换镜像源。每次换源都需要重新同步大量仓库数据，而镜像站的缓存行为各不相同，频繁换源容易造成本地仓库状态混乱。选定一个源之后至少使用一段时间，除非真的持续出问题，否则不建议反复折腾。
关于换源这件事，我最后想说的是：它治标不治本，但治标已经能解决你当前90%的痛苦了。官方源本身在国外，链路远、限流多这事情短期内很难有变化，而国内镜像站把最关键的仓库和软件包缓存都搬到了近处，日常开发体验确实和应用商店没太大差别。按照上面的步骤换完源，装软件应该就顺畅多了。如果中间遇到别的报错，最稳妥的办法就是照着报错信息去核对是环境变量配置问题还是仓库地址问题，大多数情况下都是这两处的小疏漏。
