没人喜欢给 Mac 换镜像源但每个用 Homebrew 超过三个月的人迟早都会被那根卡死不动的进度条逼到这一步。我自己的经历是某天晚上执行 brew install 一个纯命令行工具Downloading 阶段等了 8 分多钟最后 curl 超时报错重来一怒之下决定把官方源换成中科大或阿里云的镜像源。真正动手之后我才意识到Homebrew 慢并不是一个 URL 的问题而是它拿数据的方式本身分了层每一层各有各的慢法。这篇就把我怎么判断瓶颈、怎么换源、怎么验证以及换源时踩过的几个坑完整写出来给同样被官方源拖到难受的人一个可以直接照做的方案。1. 慢的根源Homebrew 的数据获取从来不是一条路Homebrew 虽然看起来只有一个命令但它背后其实是从三个完全不同的位置拿数据。搞明白这三条路径比直接复制十行 export 有用得多因为后续所有换源操作本质都是围绕这三条路径分别替换地址。1.1 三层数据来源三种不同的慢法第一层是 brew 命令本体所在的仓库。Homebrew 自己是用 git 管理的官方 origin 指向 GitHub 上的 Homebrew/brew 仓库。每次执行brew update它都要先到这个仓库做一次 git fetch虽然这个仓库不算大但网络质量差的时候照样能卡很久。第二层是 formula 和 cask 的元数据。在老版本里这一层是一个叫 homebrew-core 的 git 仓库里面有大量 formula 文件体积接近半个 GitHub 仓库的规模。传统方案里brew update要全量拉取它这也是早期 Homebrew 慢得人尽皆知的直接原因。从 4.0 开始Homebrew 改成了按需下载 JSON API 的元数据文件把这一层的数据量从git 全量仓库降到了几个 MB 的 json。慢是缓解了但 API 域名依然架在海外网络不乐观的时候照样卡。第三层是 bottle也就是预编译好的二进制包。brew install真正下载的大头都在这一层一个包几十到几百 MB 都常见。bottle 默认从 ghcr.io 拉取这个域名的连接质量如何凡是拉过大包的人应该都深有体会。关键结论是update 慢主要是第一、二层的事install 慢主要是第三层的事。只换其中一层症状最多缓解一半很多人换了镜像还是慢就是因为只解决了 bottle 这一层却没管 API 层和仓库层。1.2 先用一条命令定位你到底慢在哪一层很多人在没搞清楚瓶颈的情况下就乱换源结果换完镜像还是慢就开始怀疑镜像有问题。正确做法是先定位再做决策。time brew update time brew install jq如果brew update明显卡顿说明 git 仓库和 API 这两层有问题如果 update 很快但 install 在大尺寸 bottle 的 Downloading 阶段一动不动那瓶颈基本就在 ghcr.io 上。另外一个更直接的观察方式是用-v参数brew install jq -v输出里会明确打印出它正在访问的 URL。你看到ghcr.io/v2/homebrew/core/jq/...这类地址的时候就说明包下载走的是官方还没被镜像接管。看到具体的 URL比任何猜测都可靠。2. 换源之前的三项体检架构、版本、旧仓库残留换源不是复制一段配置就能收工。Homebrew 的版本状态不同同一套镜像配置的落点完全不一样。我见过太多人把 3.x 时代的教程往 4.x 上套改了半天 origin结果发现本地根本没有那个仓库白忙活一场。2.1 先确认你的 Mac 是哪个架构架构决定了 Homebrew 装在哪也决定了你后面操作哪个目录。uname -marm64Apple SiliconM1/M2/M3 系列Homebrew 前缀一般在/opt/homebrewx86_64Intel 芯片Homebrew 前缀一般在/usr/local拿不准直接执行brew --repo它会把当前仓库的实际路径打出来。后续所有cd 到 brew 仓库的操作都以你自己的brew --repo输出为准别硬记/opt/homebrew还是/usr/local版本迭代过程中这些路径细节很容易让人记混。2.2 版本决定换源方式3.x 看 git remote4.x 看环境变量执行brew --version看一眼大版本。如果是 3.x你的本地大概率存在 homebrew-core 这个 tap 目录换源时需要连 git remote 一起改否则 update 依然会按旧地址去 GitHub 全量拉取。如果是 4.x默认走 JSON API本地不会新建 core 仓库重点就落在 API 域名和 bottle 域名的配置上。怎么看本地有没有残留的 core/cask 仓库ls $(brew --repo)/Library/Taps/homebrew如果输出里有homebrew-core或homebrew-cask字样说明这台机器是从老版本一路升上来的或者曾经手动执行过brew tap。有残留就按第三节里的 git remote 方案一起改没有残留就只用环境变量方案事情会简单很多。另外提一句4.x 其实也保留了回到 git 模式的开关HOMEBREW_INSTALL_FROM_API默认是走 API 的一般不需要动它。但如果你发现本地明明有 core 仓库、却总感觉 update 行为不太对可以查一下这个变量的值它会在某些边缘场景下改变 Homebrew 的数据获取方式。2.3 动手前先抄一份底账方便后悔换源属于低风险操作但不是零风险。在改动之前我强烈建议先把关键信息记下来方便日后还原git -C $(brew --repo) remote -v这条命令会展示 brew 本体现在接的 origin 地址正常情况下是https://github.com/Homebrew/brew.git。如果你原来已经换过源这里显示的就是之前某个镜像的地址。抄下来后面想回官方源的时候直接照着 set-url 就行比我下面给的各种还原命令更贴合你自己的机器状态。3. 中科大与阿里云镜像的完整配置步骤现在进入正题。核心思路很简单用环境变量把 Homebrew 的 API、bottle、git 仓库三个出口全部指到国内镜像。下面分两个镜像分别给全配置顺带把老版本需要的 git remote 操作也补上。3.1 中科大镜像export 四连路径最直观中科大的仓库路径是国内镜像里最直给的没有多余前缀。在终端先手动 export 验证export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git解释一下这四个变量的职责HOMEBREW_API_DOMAIN替换 formula/cask 元数据的 JSON API 地址对应官方https://formulae.brew.sh/apiHOMEBREW_BOTTLE_DOMAIN替换预编译包的下载地址对应官方 ghcr.ioHOMEBREW_BREW_GIT_REMOTE替换 brew 本体仓库的地址HOMEBREW_CORE_GIT_REMOTE替换 core 仓库地址主要对老版本和手动 tap 场景生效手动 export 只是当前终端临时生效关掉窗口就没了。确认没问题之后要写进 shell 配置文件永久保存具体写到哪看后面的 3.4 节。3.2 阿里云镜像同样的四连路径多一层 homebrew阿里云的镜像结构和中科大不完全一样所有仓库都放在/homebrew/这个前缀下面第一次配的人特别容易在这里犯 404 的错。export HOMEBREW_API_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-core.git两个镜像的关键路径对比如下方便你一眼看出差异配置项中科大阿里云brew 仓库mirrors.ustc.edu.cn/brew.gitmirrors.aliyun.com/homebrew/brew.gitcore 仓库mirrors.ustc.edu.cn/homebrew-core.gitmirrors.aliyun.com/homebrew/homebrew-core.gitbottle 域名mirrors.ustc.edu.cn/homebrew-bottlesmirrors.aliyun.com/homebrew/homebrew-bottlesAPI 域名mirrors.ustc.edu.cn/homebrew-bottles/apimirrors.aliyun.com/homebrew/homebrew-bottles/api两个镜像怎么选我的建议是如果你的网络环境访问教育网资源比较快或者本身就在学校、研究所网段里优先中科大。如果是普通宽带或者云主机阿里云的大带宽通常更稳。两个镜像的同步频率都不低日常使用体感差距不大哪个顺手用哪个随时可以切。另外提一句清华 TUNA 也维护了一套同类的 Homebrew 镜像配置思路一模一样只是域名不同。这篇不展开你只要理解了环境变量对应的地址格式换成任何镜像都是一分钟的事。3.3 本地还留着 core/cask 仓库git remote 也要一起改如果你的机器是老版本升上来的或者曾经手动 tap 过 core/cask光设环境变量还不够brew update依然会按照本地 git 仓库里记录的 origin 去拉数据。这一步是把仓库的远程地址直接指到镜像。cd $(brew --repo) git remote set-url origin https://mirrors.ustc.edu.cn/brew.git再看有没有 core 和 cask 的本地仓库有就一起改git -C $(brew --repo homebrew/core) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git git -C $(brew --repo homebrew/cask) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git改完记得用git remote -v复查一遍。阿里云版本只要把 URL 换成上面 3.2 节里的对应地址即可。这一步做完换源才算真正闭环。提示brew --repo homebrew/core这个写法只有在本地确实存在该 tap 时才有意义。本地不存在时它会报错提示无效的 tap 名看到报错别慌说明你的环境根本不需要改它跳过就好。3.4 写入 shell 配置让新终端也保持镜像临时 export 只对当前终端有效开一个新窗口就没了。macOS 默认 shell 是 zsh所以配置文件一般是~/.zshrc。用追加方式写进去cat ~/.zshrc EOF export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git EOF然后执行source ~/.zshrc或者干脆开一个新的终端窗口。如果你用的不是 zsh而是 fish 之类的 shell语法要换成 fish 自己的set -gx HOMEBREW_API_DOMAIN https://mirrors.ustc.edu.cn/homebrew-bottles/api写完别急着安装软件先做一步验证env | grep HOMEBREW能看到你刚才设置的四个变量说明配置已经被当前 shell 加载。看不到就去检查是不是 source 失败了或者变量写进了错误的配置文件。4. 换源后的效果验证别凭感觉说快用数据说话换完源最怕的就是感觉好像快了又好像没快。建议按下面三步走完每一步都有明确输出能让你清楚地知道配置到底生效没有。4.1 先看 brew config 的输出brew config这个命令会打印 Homebrew 当前的核心配置。重点看两个位置一是ORIGIN字段正常应该显示你设置的镜像仓库地址比如https://mirrors.ustc.edu.cn/brew.git二是输出里的有关 Homebrew 环境变量段确认 API 和 bottle 域名都是镜像地址。如果ORIGIN显示的依然是 GitHub 官方地址说明 brew 仓库本体的远程还没改对回到 3.3 节检查 git remote。这一步排查对换完源还是慢的情况特别管用因为环境变量能改的是行为逻辑本地 git 的 origin 决定的是实际请求打到哪台服务器上。4.2 用 curl 直接测两个镜像的下载速度与其反复 install 测试不如先用 curl 看原始速度。这里选一个固定文件来对比curl -o /dev/null -s -w 下载时间: %{time_total}s, 平均速度: %{speed_download} 字节/秒\n https://mirrors.ustc.edu.cn/homebrew-bottles/api/formula.jws.json把 URL 换成阿里云的对应地址再跑一次顺手对比一下两个镜像在你当前网络下的速度。我实测下来多数情况下国内镜像能把速度从几十 KB/s 的蠕爬拉到几 MB/s 起跳如果宽带条件好差距会看得更清楚。这个文件本身不大测的是连接质量和首包速度代表的是日常元数据请求的体感真正评估大包下载还是得靠实际安装。4.3 实际安装一个包看整体耗时和日志行测速只能说明链路快最终还是要回归到brew install的整体体验time brew install jq第一次运行时Homebrew 会额外下载 JSON API 索引可能比平时慢一点点这是正常现象下一次安装就会快很多。装一个几十 MB 的包对比换源前后的体感最明显。另外注意brew update的输出也会变得干净利落。以前可能是卡在 Updating Homebrew... 半天不动换源之后几秒内就能完成。如果 update 之后提示Already up-to-date先别怀疑这是正常状态说明你的仓库已经和镜像源同步到最新了。5. 换源路上的坑我把常见翻车现场都替你过了一遍换源本身不复杂但真动手的时候几乎每个人都会在下面这几个地方至少卡一次。我把翻车场景和排查思路都列出来你遇到问题直接对号入座。5.1 404/403 报错九成是域名路径没对齐最常见的报错长这样curl: (22) The requested URL returned error: 404位置卡在 Downloading 阶段。第一反应别去怀疑镜像挂掉了先检查是不是把两个镜像的路径拼错了。典型错误就是把中科大的路径直接套到阿里云域名后面比如写了https://mirrors.aliyun.com/homebrew-bottles/api真实地址却在homebrew目录下面。404 的本质就是地址不存在把表里的路径逐字对一遍通常就能找到问题。还有一种情况是 API 域名和 bottle 域名没有成对设置。比如只设置了HOMEBREW_BOTTLE_DOMAINAPI 域名还留在官方Homebrew 从官方 API 拿到元数据后再按镜像路径去下载 bottle两边版本信息一旦有细微差异就可能算出一个镜像上不存在的 URL表现同样是 404。所以四个环境变量不要只挑两三个设一次性设全最省事。5.2 环境变量管住的是新克隆本地 origin 才是老大这是我换源过程中最有价值的一个发现。很多教程只教设置HOMEBREW_BREW_GIT_REMOTE但对已经安装在机器上的 Homebrew 来说这个变量主要影响的是安装脚本和新建克隆时使用的远程地址。你本地的 brew 仓库是早期 clone 下来的它的 origin 还指向 GitHub运行brew update时实际走的还是本地 git remote 那条路。所以判断 update 慢的问题时先看本地仓库的 origingit -C $(brew --repo) remote -v如果显示 GitHub 官方地址光有环境变量没用必须执行 3.3 节的git remote set-url。这也是换完源还是慢这个高频问题的最常见原因我自己第一次就栽在这上面环境变量配得漂漂亮亮结果 update 依旧磨蹭查了半天才发现本地 origin 根本没动。5.3 写了 export 却不生效按这个顺序排查如果你确认自己写了配置新终端里env | grep HOMEBREW却空空如也按下面顺序查确认配置文件写对了。macOS 默认 zsh 读~/.zshrc如果你用 bash 却写进了.bash_profile主 shell 是 zsh 的话根本不会加载。确认写的是 export不是裸赋值。HOMEBREW_API_DOMAINxxx在 shell 里只是普通变量不会传给子进程。确认写完执行过source ~/.zshrc或者真的开了一个新窗口。很多终端软件会复用旧会话环境不会自动刷新。如果用 fish 这类非 POSIX shellexport语法不适用要用set -gx。这四条走完99% 的不生效问题都能解决。剩下的 1%基本是终端启动了多个 shell 环境比如某些 IDE 内置终端只继承了 IDE 启动时的环境变量这种直接重启 IDE 就好。5.4 镜像同步有延迟新版本 bottle 偶尔会 404镜像再好本质上也是定时从官方同步不可能做到实时。某天你 brew install 一个新发布的版本镜像上可能还没有对应的 bottle这时报 404 很正常不代表你的配置出了问题。我的处理方式是先等一下镜像的同步周期通常以小时计过几个小时再试。等不及就临时绕开镜像只装这一次unset HOMEBREW_BOTTLE_DOMAIN brew install 那个包装完再把环境变量 source 回来。不建议为了这一个包改成源码编译那才是真的又慢又容易踩新的坑。如果频繁遇到这种 404可以换个镜像试试不同镜像的同步节奏不完全一致有些包在这个镜像上没有在另一个镜像上可能已经有了。6. 回归官方源和日常使用的几个小习惯换源不是一劳永逸的事但也不是什么高风险操作。什么时候要回官方源比如你此后要长期访问海外网络环境或者镜像源临时抽风这时候需要把改动撤销掉。6.1 一键还原官方源还原分两步先把 git remote 改回官方再清理环境变量。改 remotecd $(brew --repo) git remote set-url origin https://github.com/Homebrew/brew.git如果有本地 core/cask 仓库同样把 URL 改回github.com/Homebrew/homebrew-core.git和github.com/Homebrew/homebrew-cask.git。然后去~/.zshrc里删除那几个 export 行source ~/.zshrc即可。改完后执行一次brew update看到它正常走官方源就算还原成功。6.2 让 Homebrew 日常更快的小建议最后分享几个我一直在用的习惯配合镜像源组合起来效果更好给brew install加上环境变量HOMEBREW_NO_AUTO_UPDATE1可以省掉每次安装前自动 update 的等待。注意这只是跳过自动检查你仍然应该定期手动执行brew update否则 formula 版本会越来越陈旧。定期执行brew cleanup清理旧版本的 bottle你会发现磁盘占用比想象中还容易堆积。新机器装 Homebrew 时可以把HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE预先 export 再跑官方安装脚本装完直接就是镜像源省得再改一遍。cask 安装的 GUI 应用很多是直接从软件厂商官网下载安装包的这一部分镜像管不到下载慢的话别把锅扣在换源方案头上。我个人折腾下来的最终选择是中科大的镜像主要因为它路径结构清晰我所在网络环境下访问它也确实稳定。但从实际操作来看阿里云的表现同样可靠关键不是选哪一个而是搞清楚分层配置的逻辑别在一个地方用死理也别指望换完源就一劳永逸。镜像同步有延迟、本地 origin 没改干净、环境变量写错文件这些坑我都替你踩过了照着上面的流程走基本不会有第二个难眠的深夜。