1. 为什么你需要一个“一键更新镜像源”的脚本
先聊个真实场景:你兴冲冲地在 Mac 上执行 brew install wget,结果终端卡在 Updating Homebrew... 半小时不动,最后直接报错 Failed to connect to github.com port 443: Operation timed out。这种体验我太熟悉了,尤其是网络环境不太理想的时候,Homebrew 默认从 GitHub 拉取仓库和二进制包,而 GitHub 的连接质量大家都懂,跟开盲盒一样——有时候快得离谱,有时候连个响应都没有。
于是“换镜像源”就成了 Mac 用户绕不开的话题。所谓镜像源,本质上就是官方仓库的“本地缓存副本”。国内有很多高校和云厂商维护自己的 Homebrew 镜像,比如清华 TUNA、中科大 USTC、阿里云,它们会定期同步 GitHub 上的 Homebrew 仓库,你从这些镜像下载时走的是国内线路,速度能快几十倍。
但这里有个坑:镜像源不是一劳永逸的。你换成中科大源之后,可能过几天中科大镜像挂了、或者你想换回官方源、或者公司网络换了导致某个镜像访问不了。每次都要手动敲一堆 export 命令、修改 git remote、替换 formula 下载地址,繁琐不说,还容易敲错。所以我就手写了一个“MAC OS 更新 homebrew 镜像源脚本”,把整个换源、更新、校验、恢复的过程全部自动化,今天把这个脚本的思路和完整实现分享出来。
这个脚本适合谁?第一类是刚接触 Homebrew 不久、被网络问题折腾到崩溃的新手,你可以直接拿去用;第二类是需要在多台 Mac 上反复配置开发环境的工程师,省得每台机器手动敲;第三类是单纯想搞懂“Homebrew 镜像源到底改的是哪些配置”的好奇派,把脚本读一遍,你的理解会比网上大多数教程深得多。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 在写脚本之前,先弄懂 Homebrew 镜像源的底层配置
2.1 Homebrew 的更新链路到底长什么样
想写出靠谱的脚本,第一步是理解 Homebrew 更新时到底访问了哪些地址。Homebrew 不是单体应用,它由数个模块组成,它们各自的下载源是独立的:
- Homebrew 本体仓库(brew 命令的源码):默认地址是
https://github.com/Homebrew/brew.git,brew update时会拉取这个仓库的更新。 - Homebrew/homebrew-core(核心软件包仓库):默认地址是
https://github.com/Homebrew/homebrew-core.git,这是brew install时检索包定义的地方。 - homebrew-bottles(预编译二进制包):
brew install下载的不是源码编译,而是直接拉取编译好的 bottle 包,默认从ghcr.io(GitHub Container Registry)下载。这个域名在国内的访问情况比 github.com 还惨,经常直接超时。 - homebrew-cask(图形化应用仓库):如果你用
brew install --cask装 Chrome、VS Code 这类 App,走的就是这个仓库。
明白了这条链路,你就清楚换源的本质了——把上面四类地址从 GitHub 替换成国内镜像,并且换完源之后还要让系统依然可以正常安装软件,不只是改个 git remote 那么简单。
2.2 镜像源的“姿势”差异:HOMEBREW_API_DOMAIN 与 git remote
在 macOS 的新版 Homebrew 上,镜像源配置比网上老教程里写的复杂一些。老教程一般只让你改三行 git remote set-url,但在 Homebrew 4.x 之后,默认开启了对 JSON API 的支持。
你可以在终端里执行 brew config,看输出中是否存在 HOMEBREW_API_DOMAIN 这个环境变量。如果为空,说明 brew 默认从 GitHub 拉取 formula 的 JSON 元数据;而国内镜像(比如清华)提供的 https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api 路径下就有这些 JSON 文件。
所以,一个兼容新旧版本的换源脚本,不能只改 git remote,还需要把 HOMEBREW_API_DOMAIN 和 HOMEBREW_BOTTLE_DOMAIN 这两个环境变量写入 shell 配置文件,否则就算 git remote 换成清华,API 拉取仍会走 GitHub,速度瓶颈根本解决不了。
2.3 哪些配置项需要写进脚本里
我梳理了一下,一个完整的 Homebrew 换源脚本至少要覆盖以下配置项:
| 配置项 | 默认地址 | 镜像替换目标 | 作用 |
|---|---|---|---|
| HOMEBREW_API_DOMAIN | https://formulae.brew.sh | 清华/中科大 API 地址 | 拉取软件包元数据 JSON |
| HOMEBREW_BOTTLE_DOMAIN | https://ghcr.io | 清华/中科大 bottle 地址 | 下载预编译二进制包 |
| HOMEBREW_BREW_GIT_REMOTE | https://github.com/Homebrew/brew.git | 镜像的 brew.git | Homebrew 本体仓库 |
| HOMEBREW_CORE_GIT_REMOTE | https://github.com/Homebrew/homebrew-core.git | 镜像的 homebrew-core.git | 软件包定义仓库 |
| HOMEBREW_CASK_GIT_REMOTE | https://github.com/Homebrew/homebrew-cask.git | 镜像的 cask.git | 图形化应用仓库 |
注意,有些镜像(比如阿里云)不提供 cask 仓库的镜像,这时候脚本里就要做分支判断。这也是我写脚本时比较重视的一点——不能把镜像源地址写死成一家,要允许用户自由选择。
3. 脚本设计思路与整体架构
3.1 我为什么不直接用网上别人写好的镜像脚本
如果你在 GitHub 上搜 homebrew mirror script,能找到很多现成项目。但我在实际使用中发现几个问题:有些脚本只适配了旧版 Homebrew,跑在新版本上 API 还是走 GitHub;有些脚本写死了中科大或者清华的地址,用户想换一家就得手动改脚本源码;还有些脚本直接覆盖 ~/.zshrc,把用户原本配置的别名、路径变量全冲掉了。
所以我决定自己写一个,目标很明确:
- 幂等性:脚本可以反复执行,不会因为重复跑而产生配置冲突。
- 可逆向:提供“恢复官方源”的功能,任何时候想反悔都能一键还原。
- 可选性:用户通过命令行参数选择中科大、清华或阿里云,而不是改代码。
- 安全性:不覆盖 shell 配置文件的原有内容,只做追加或精准替换。
3.2 脚本的整体流程
整个脚本分成五个阶段,逻辑上是一个线性的流程:
- 前置检查:确认系统是 macOS、确认 Homebrew 已安装、确认存在
HOMEBREW_PREFIX环境变量。 - 选择镜像源:通过参数或交互菜单让用户选择中科大、清华或阿里云。
- 配置环境变量:往
~/.zshrc(或~/.bash_profile)写入镜像地址。 - 切换 git remote:进入 Homebrew 安装目录,逐个仓库替换远程地址。
- 更新验证:执行
brew update并用brew config检查关键字段是否生效。
3.3 镜像源地址映射表
不同镜像站提供的路径结构差别很大,这里我先整理一份我当时收集的地址映射,脚本的核心就是这张表:
| 镜像站 | Brew 仓库地址 | Homebrew-core 地址 | API 地址 | Bottle 地址 |
|---|---|---|---|---|
| 中科大 USTC | https://mirrors.ustc.edu.cn/brew.git |
https://mirrors.ustc.edu.cn/homebrew-core.git |
https://mirrors.ustc.edu.cn/homebrew-bottles/api |
https://mirrors.ustc.edu.cn/homebrew-bottles |
| 清华 TUNA | https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git |
https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git |
` |
