上个月帮一位同事修了一台非常典型的MacHomebrew装得好好的但每次执行brew install光卡在Updating Homebrew...那个阶段就能卡掉好几分钟偶尔还会冒出一串网络超时的报错。我远程看了一眼他确实照网上的教程手动换过镜像源但只换了一半。新版本Homebrew默认走API拉取formula数据下载预编译包也走另一套独立域名这两条链路他完全没走镜像。那天我干脆把之前写好的一份homebrew镜像源更新脚本丢给他跑了一遍几分钟内就把git仓库、API域名、bottle下载域名全部切到国内源。这篇文章就把这个脚本从设计、实现到实测翻车的完整过程拆开讲一遍给还卡在装完Homebrew却慢成狗这件事上的朋友做个参考。1. Homebrew换源到底换的是什么先摸清慢的根源很多人对换源的理解停留在把git地址换掉。这个认知在三四年前没问题但现在的Homebrew已经演进了换源的概念必须跟着更新。1.1 慢在git还是在API新版Homebrew的元数据获取链路旧版Homebrew的工作方式很直白每次执行brew install之前它都会把你本地的homebrew-core仓库做一次git fetch拿到最新的formula描述文件再解析出你要装的包。这种设计天然依赖git仓库的clone和fetch速度GitHub在国内网络环境下经常几十KB/s卡顿就成了常态。从Homebrew 4.0开始事情变了。官方默认不再要求本地维护一个完整的homebrew-coregit仓库而是启动时直接请求formulae.brew.sh的接口拉一份JSON格式的formula索引下来这部分叫API数据。安装软件时预编译的二进制包bottles则统一从ghcr.ioGitHub Container Registry下载这个域名在国内的访问速度更加玄学。我把整条链路拆开之后发现换源其实必须覆盖三层brew主仓库的git remote负责brew update时拉取Homebrew自身代码。formula元数据的API域名负责解析软件依赖、版本信息。bottles二进制包的下载域名负责真正安装软件时的包下载。网上一大堆旧教程只做了第一层所以很多人照着操作完发现该慢还是慢原因就是第二层和第三层根本没被覆盖。1.2 一份完整镜像配置应包含的三层替换既然知道有三条链路对应的配置项也就清楚了。依次对应下面的设置链路旧版方案新版方案Homebrew主仓库git remote set-url origin 镜像brew.gitgit remote set-url origin 镜像brew.git同时设置HOMEBREW_BREW_GIT_REMOTEhomebrew-core仓库git remote set-url origin 镜像core.git4.0后默认不再本地clone但可以设HOMEBREW_CORE_GIT_REMOTE备用formula元数据API走本地git仓库设置HOMEBREW_API_DOMAIN指向镜像API地址bottles二进制包设置HOMEBREW_BOTTLE_DOMAIN同样设置HOMEBREW_BOTTLE_DOMAIN所以我写脚本的时候目标就非常具体一次性把HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN这四个变量和本地的git remote全部处理好。只有这样才能算真正换源而不是自欺欺人地只换一个仓库地址。2. 镜像源选型与功能边界写脚本前的三件事2.1 中科大、清华、阿里云镜像源对比为什么默认选中科大动手写脚本前我先比较了国内几个主流的Homebrew镜像源核心对比项有三点是否提供完整的bottles下载、API域名是否可用、同步频率是否稳定。镜像源git仓库API/bottles我的使用评价中科大 USTCmirrors.ustc.edu.cn/brew.git等提供homebrew-bottles目录包含API和bottle最省事一个域名解决API和bottle两层是我主力源清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrew/主要提供git仓库bottles目录不够完整git仓库速度很好但bottles需要搭配其他源用阿里云mirrors.aliyun.com/homebrew/提供homebrew-bottles目录稳定性不错适合作为备用源最终我默认选择了中科大。原因很简单它的homebrew-bottles路径下同时挂着api子目录和实际的bottles包文件一个基础域名就能同时供给HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN脚本逻辑会简单很多。而且中科大的同步节奏在几个源里属于比较勤快的新发布的formula版本基本隔天就能镜像到。阿里云作为备用源写进了脚本的变量体系里万一中科大临时抽风一条命令就能切过去。2.2 脚本的功能边界该做的与不该做的确定了源接下来是功能边界。市面上很多换源教程就是给你几条git remote set-url命令丢给你自己复制粘贴。这种思路在全新环境上也许能跑通但一旦遇到Apple Silicon新路径、Homebrew 4.0的API链路、zsh环境变量不生效这类情况立刻歇菜。我给脚本定的职责清单是这样的自动识别macOS版本、CPU架构、当前Shell类型决定Homebrew安装路径和需要写入的配置文件。自动探测homebrew-core、homebrew-cask本地目录是否存在存在才做git remote替换不存在就跳过。持久化HOMEBREW_API_DOMAIN等环境变量到正确的shell配置文件且重复执行不会产生重复配置。替换前自动备份原始remote URL支持一条命令回滚官方源。换源完成后自动跑一次brew update做验证。同时我也明确了脚本不该做什么不负责安装Homebrew本体不处理网络链路完全不通的问题不主动清理缓存。边界想清楚脚本才不会越管越宽最后变成一团浆糊。3. 逐模块拆解脚本实现环境探测、源替换与变量持久化下面进入正题我把脚本拆成三段来讲每一段都可以单独拿来复用。3.1 环境探测版本、架构、Shell 一个都不能少脚本的第一件事是搞清楚自己运行在什么环境里。我最初写的版本偷懒直接用command -v brew定位仓库结果在一台全新Mac上压根没找到brew整个脚本直接报错退出。后来改成先探测架构再推断安装路径再回退到brew --repo逻辑就稳了。#!/usr/bin/env bash set -euo pipefail # 镜像源基础地址可通过环境变量覆盖方便切换 MIRROR_BASE${MIRROR_BASE:-https://mirrors.ustc.edu.cn} BREW_GIT_REMOTE${BREW_GIT_REMOTE:-$MIRROR_BASE/brew.git} CORE_GIT_REMOTE${CORE_GIT_REMOTE:-$MIRROR_BASE/homebrew-core.git} CASK_GIT_REMOTE${CASK_GIT_REMOTE:-$MIRROR_BASE/homebrew-cask.git} BOTTLES_DOMAIN${BOTTLES_DOMAIN:-$MIRROR_BASE/homebrew-bottles} API_DOMAIN${API_DOMAIN:-$BOTTLES_DOMAIN/api} OS_VERSION$(sw_vers -productVersion) ARCH$(uname -m) if [[ $ARCH arm64 ]]; then HOMEBREW_PREFIX/opt/homebrew else HOMEBREW_PREFIX/usr/local fi BREW_REPO${HOMEBREW_PREFIX}/Homebrew if command -v brew /dev/null 21; then BREW_REPO$(brew --repo) fi这里有个细节值得说为什么要用uname -m而不是arch命令因为Apple Silicon的Terminal里执行arch默认可能返回i386/x86_64有时候会被Rosetta环境干扰而uname -m拿到的是当前内核的真实架构判断Apple Silicon更可靠。Shell类型检测同理。macOS从Catalina开始默认Shell是zsh但你没法保证用户没有切回bash所以我做了两层判断分别对应~/.zshrc和~/.bash_profile。SHELL_RC$HOME/.zshrc case $SHELL in */bash) SHELL_RC$HOME/.bash_profile ;; */zsh) SHELL_RC$HOME/.zshrc ;; esac不写bashrc而写bash_profile是因为macOS上bash的登录Shell默认加载的是profile系列文件把环境变量塞进bashrc经常在图形界面终端里不生效。3.2 核心替换段git remote 与四个环境变量的配合环境探测完进入真正的替换逻辑。第一件事永远是备份而不是上来就改。我的做法是把当前remote URL写进一个带时间戳的临时文件回滚时直接读这个文件恢复。BACKUP_FILE/tmp/homebrew_git_backup_$(date %Y%m%d%H%M%S).txt echo $BREW_REPO $(git -C $BREW_REPO remote get-url origin 2/dev/null || echo ) $BACKUP_FILE接下来是git remote替换。这里必须根据目录是否存在做判断因为Homebrew 4.0默认安装机制下很多环境根本没有homebrew-core这个本地git目录强行执行git -C会报没有那个目录的错这也是网上不少教程抄了之后反而搞坏环境的原因。if [[ -d $BREW_REPO/.git ]]; then git -C $BREW_REPO remote set-url origin $BREW_GIT_REMOTE fi CORE_DIR$BREW_REPO/Library/Taps/homebrew/homebrew-core CASK_DIR$BREW_REPO/Library/Taps/homebrew/homebrew-cask if [[ -d $CORE_DIR/.git ]]; then git -C $CORE_DIR remote set-url origin $CORE_GIT_REMOTE fi if [[ -d $CASK_DIR/.git ]]; then git -C $CASK_DIR remote set-url origin $CASK_GIT_REMOTE fi环境变量的持久化我用的是先清理再追加策略。直接追加会导致重复执行脚本时变量堆积后面的export覆盖前面的配置看起来一团乱。用grep -q判断存在再决定是否写入逻辑更干净。grep -q set homebrew mirror by script $SHELL_RC 2/dev/null \ sed -i /# --- set homebrew mirror by script/,/^$/d $SHELL_RC { echo echo # --- set homebrew mirror by script --- echo export HOMEBREW_API_DOMAIN\$API_DOMAIN\ echo export HOMEBREW_BOTTLE_DOMAIN\$BOTTLES_DOMAIN\ echo export HOMEBREW_BREW_GIT_REMOTE\$BREW_GIT_REMOTE\ echo export HOMEBREW_CORE_GIT_REMOTE\$CORE_GIT_REMOTE\ } $SHELL_RC这里一定要提醒macOS自带的sed是BSD版本-i参数后面必须紧跟一个空字符串写成-i不带参数会直接报错。这个坑我在Linux上写脚本习惯后切回macOS踩过一次。3.3 验证与回滚脚本不是做完就跑替换完不验证等于白做。我加了两层验证第一层是探测镜像源连通性第二层是执行一次真实的brew update。HTTP_CODE$(curl -s -o /dev/null -w %{http_code} -I $BOTTLES_DOMAIN/) if [[ $HTTP_CODE ! 200 $HTTP_CODE ! 403 $HTTP_CODE ! 301 ]]; then echo WARNING: 镜像源连通性异常HTTP $HTTP_CODE fi source $SHELL_RC brew update403和301在镜像站里经常出现有的镜像根路径会返回重定向有的会返回Forbidden但不影响实际资源访问所以不能只认200。把这几个状态码都放行后误报率低很多。回滚逻辑也不复杂就是把备份文件里的remote URL逐行恢复回去同时把shell配置文件里的环境变量整段删掉。#!/usr/bin/env bash # --- 回滚模式 --- if [[ ${1:-} --rollback ]]; then LATEST_BACKUP$(ls -t /tmp/homebrew_git_backup_*.txt 2/dev/null | head -n1) if [[ -z $LATEST_BACKUP ]]; then echo 没有找到备份文件无法回滚 exit 1 fi while read -r repo url; do [[ -n $repo -n $url ]] git -C $repo remote set-url origin $url done $LATEST_BACKUP sed -i /# --- set homebrew mirror by script/,/^$/d $SHELL_RC echo 已回滚官方源请注意执行 source $SHELL_RC exit 0 fi设计回滚的初衷很朴素镜像源偶尔会抽风也可能某天你想把环境还原成官方配置。有这个入口在脚本就不再是一次性工具而是个可以持续用的维护工具。4. 实测记录脚本上线后遇到的五个真实问题脚本写出来只是开始真正有价值的坑全在实测阶段。这五个问题我一个个记录排查过程每一个都对应一种典型环境。4.1 换了core源仍然慢新版Homebrew走了API路径第一次跑完脚本我自信满满地在一台测试机上执行brew update结果依旧卡了几十秒。第一反应是不是镜像源挂了但curl直连镜像速度很快。后来用brew update --verbose查看详细输出发现它一开始请求的域名是formulae.brew.sh压根不是我设置的中科大API。原因很直接环境变量虽然写进了~/.zshrc但当前这个终端会话是在写之前就启动的环境变量根本没加载。执行source ~/.zshrc后brew config看到HOMEBREW_API_DOMAIN已经指向中科大再跑brew update瞬间就过了。这个案例说明两件事脚本里一定要加source动作或明确提示以及验证环境变量是否生效最靠谱的命令是brew config它会列出所有HOMEBREW_*变量的实际取值。另外还有一个隐藏变量值得注意HOMEBREW_INSTALL_FROM_API。新版Homebrew默认值为1走API路径。如果某些老教程或自定义配置把它显式设置为0Homebrew会强制回到git clone homebrew-core的模式那就算API域名换了也没用。我在脚本里补了一行显式导出HOMEBREW_INSTALL_FROM_API1把这条路径锁死。4.2 老系统遇上新版本this version of mac os is not supported的真相排查第二台机器时遇到的是启动报错终端直接弹出一行红字this version of mac os is not supported on this platform。这台机器是某款2015年的MacBook系统还停在Big Sur。原因是Homebrew主程序一直在往前迭代新版本对macOS的最低版本要求不断抬升老系统已经处于官方支持边界之外。这种现象和镜像源没有直接关系但恰恰是写换源脚本时必须考虑的前置条件——一个老系统连brew都无法运行时换源根本无从谈起。我的处理方式是给脚本加了一段系统版本预检if [[ $(echo $OS_VERSION | cut -d. -f1) -lt 12 ]]; then echo WARNING: 当前系统为 macOS $OS_VERSION新版 Homebrew 可能不受支持 fi注意这里只是警告不是直接退出。因为老系统用户可以手动安装旧版本Homebrew或者从已有环境迁移过来。但脚本至少要给出提示避免用户在不明不白的情况下继续执行最后被一屏报错淹没。4.3 Apple Silicon与Rosetta双brew并存时的替换陷阱第三台机器是M1 MacBook Pro问题更隐蔽。执行brew --repo得到的是/opt/homebrew路径脚本也顺利把路径替换了但用户实际在/usr/local下还装了一套x86_64的Homebrew那是当初用Rosetta终端装的。两套brew并存终端默认加载的是arm64那套脚本只处理了它。这种情况如果不处理会出现诡异的现象脚本跑完当前终端的brew确实换好源了但用户一旦用Rosetta终端打开那套老brew还是官方源依然慢成狗。我在脚本里加了一个检测如果/usr/local/Homebrew和/opt/homebrew两个目录同时存在就提示用户当前只处理激活的那一套如果需要两套都换可以显式指定路径执行。多数用户其实只需要arm64那套但至少要有知情权。顺带发现一个常见后遗症/opt/homebrew目录属主如果是rootbrew install时会出现权限报错处理方式就是sudo chown -R $(whoami) /opt/homebrew这个也写进了提示。4.4 环境变量持久化后不生效配置文件与加载时机第四个问题来自一个很日常的场景脚本写完环境变量用户打开一个新终端标签页跑brew config发现变量还是空的。我一开始怀疑是Shell配置写错了手动检查文件内容变量确实在里面。后来才发现是iTerm2的问题——它默认的新标签页不加载~/.zshrc需要设置里面打开登录Shell选项。这种情况本质上是配置文件写对了但加载时机不对。macOS终端的默认行为是login shell会加载profile相关文件但一些第三方终端模拟器或者用户手动改过启动命令可能变成非login模式~/.zshrc就不会被自动加载。脚本层面能做的有限我只能做两件事一是写入后立即source一次保证当前会话生效二是输出一行提示告诉用户如果新开终端仍然不生效检查终端是否以login shell模式运行。这个问题虽然不是脚本能根治的但提前提示能省用户大量排查时间。4.5 镜像源临时不可用如何切换备用源而不破坏配置最后一个问题不是bug而是运维场景某天下午中科大镜像站响应变得很慢brew install又开始超时。用户不知所措问我是不是要从头再跑一遍新脚本。答案是不需要。我在脚本设计时把镜像基础地址做成了环境变量切换源只需要在命令前面临时覆盖MIRROR_BASEhttps://mirrors.aliyun.com ./homebrew_mirror.sh执行完脚本内的所有${MIRROR_BASE}都会替换成阿里云地址相当于用同一个脚本完成了从A镜像切到B镜像的全过程。回滚、验证、环境变量更新照常工作。这种设计带来的额外好处是你想比较两个镜像哪个快直接跑两遍脚本再分别time brew update一次数据就出来了。我实际测过中科大和阿里云在晚高峰时段的速度差异还挺明显中科大低谷期能跑到几MB/s阿里云高峰期的延迟则更稳定一些。5. 脚本如何日常使用我的维护习惯与体会脚本跑通后落地成日常习惯的周期其实很短。我现在维护这套脚本的方式值得分享一下。第一脚本文件不再往/tmp丢而是放进~/bin目录同时纳入dotfiles仓库管理。这样换新机器时一条同步命令就能把脚本带过去。但我不太建议用网络上curl一行管道直接执行的方式分发这类脚本尤其是涉及改git remote和环境变量的操作你自己都不知道那段脚本在背后干了什么风险太高。自己维护一份逐行能看懂才是最稳的。第二使用时机总结下来就这么几个刚安装完Homebrew之后马上跑一次Homebrew大版本升级后跑一次镜像源连续超时的时候跑一次。没有必要频繁执行因为它本质上是配置调整不是常驻服务。第三也是我最近才意识到的换源脚本最怕的不是命令写错而是不知道Homebrew实际走了哪条链路。所以排查问题时我第一反应永远是看brew config确认四个HOMEBREW_*变量的实际值辅以brew update --verbose观察请求域名。只要这两条命令跑出来的结果符合预期那Homebrew慢的问题就已经排除了大半。最后再说一个边界情况镜像源不是万能的。某些通过Cask安装的软件包体本身托管在GitHub Releases里这部分流量依然走官方域名还有少量仓库不在Homebrew默认仓库里是第三方tap这类tap的clone请求也不会走你配置的core镜像。遇到这种情况不用怀疑脚本失效它是正常的——换源解决的是Homebrew经典链路问题而不是所有网络问题。四台机器全部换源完成后我最大的感受是好的脚本不是把所有操作堆在一起而是每一段都明确知道自己为什么要这么做。换源这件事本身不难难的是把新版Homebrew的API链路、不同架构的路径差异、Shell配置的加载机制全都理顺。把这套逻辑写成脚本后以后再遇到谁跟我说Homebrew慢到没法用我只需要递过去一行命令跑一下然后brew update完事。
Homebrew换源实战：从API到Bottles完整配置脚本解析
上个月帮一位同事修了一台非常典型的MacHomebrew装得好好的但每次执行brew install光卡在Updating Homebrew...那个阶段就能卡掉好几分钟偶尔还会冒出一串网络超时的报错。我远程看了一眼他确实照网上的教程手动换过镜像源但只换了一半。新版本Homebrew默认走API拉取formula数据下载预编译包也走另一套独立域名这两条链路他完全没走镜像。那天我干脆把之前写好的一份homebrew镜像源更新脚本丢给他跑了一遍几分钟内就把git仓库、API域名、bottle下载域名全部切到国内源。这篇文章就把这个脚本从设计、实现到实测翻车的完整过程拆开讲一遍给还卡在装完Homebrew却慢成狗这件事上的朋友做个参考。1. Homebrew换源到底换的是什么先摸清慢的根源很多人对换源的理解停留在把git地址换掉。这个认知在三四年前没问题但现在的Homebrew已经演进了换源的概念必须跟着更新。1.1 慢在git还是在API新版Homebrew的元数据获取链路旧版Homebrew的工作方式很直白每次执行brew install之前它都会把你本地的homebrew-core仓库做一次git fetch拿到最新的formula描述文件再解析出你要装的包。这种设计天然依赖git仓库的clone和fetch速度GitHub在国内网络环境下经常几十KB/s卡顿就成了常态。从Homebrew 4.0开始事情变了。官方默认不再要求本地维护一个完整的homebrew-coregit仓库而是启动时直接请求formulae.brew.sh的接口拉一份JSON格式的formula索引下来这部分叫API数据。安装软件时预编译的二进制包bottles则统一从ghcr.ioGitHub Container Registry下载这个域名在国内的访问速度更加玄学。我把整条链路拆开之后发现换源其实必须覆盖三层brew主仓库的git remote负责brew update时拉取Homebrew自身代码。formula元数据的API域名负责解析软件依赖、版本信息。bottles二进制包的下载域名负责真正安装软件时的包下载。网上一大堆旧教程只做了第一层所以很多人照着操作完发现该慢还是慢原因就是第二层和第三层根本没被覆盖。1.2 一份完整镜像配置应包含的三层替换既然知道有三条链路对应的配置项也就清楚了。依次对应下面的设置链路旧版方案新版方案Homebrew主仓库git remote set-url origin 镜像brew.gitgit remote set-url origin 镜像brew.git同时设置HOMEBREW_BREW_GIT_REMOTEhomebrew-core仓库git remote set-url origin 镜像core.git4.0后默认不再本地clone但可以设HOMEBREW_CORE_GIT_REMOTE备用formula元数据API走本地git仓库设置HOMEBREW_API_DOMAIN指向镜像API地址bottles二进制包设置HOMEBREW_BOTTLE_DOMAIN同样设置HOMEBREW_BOTTLE_DOMAIN所以我写脚本的时候目标就非常具体一次性把HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN这四个变量和本地的git remote全部处理好。只有这样才能算真正换源而不是自欺欺人地只换一个仓库地址。2. 镜像源选型与功能边界写脚本前的三件事2.1 中科大、清华、阿里云镜像源对比为什么默认选中科大动手写脚本前我先比较了国内几个主流的Homebrew镜像源核心对比项有三点是否提供完整的bottles下载、API域名是否可用、同步频率是否稳定。镜像源git仓库API/bottles我的使用评价中科大 USTCmirrors.ustc.edu.cn/brew.git等提供homebrew-bottles目录包含API和bottle最省事一个域名解决API和bottle两层是我主力源清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrew/主要提供git仓库bottles目录不够完整git仓库速度很好但bottles需要搭配其他源用阿里云mirrors.aliyun.com/homebrew/提供homebrew-bottles目录稳定性不错适合作为备用源最终我默认选择了中科大。原因很简单它的homebrew-bottles路径下同时挂着api子目录和实际的bottles包文件一个基础域名就能同时供给HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN脚本逻辑会简单很多。而且中科大的同步节奏在几个源里属于比较勤快的新发布的formula版本基本隔天就能镜像到。阿里云作为备用源写进了脚本的变量体系里万一中科大临时抽风一条命令就能切过去。2.2 脚本的功能边界该做的与不该做的确定了源接下来是功能边界。市面上很多换源教程就是给你几条git remote set-url命令丢给你自己复制粘贴。这种思路在全新环境上也许能跑通但一旦遇到Apple Silicon新路径、Homebrew 4.0的API链路、zsh环境变量不生效这类情况立刻歇菜。我给脚本定的职责清单是这样的自动识别macOS版本、CPU架构、当前Shell类型决定Homebrew安装路径和需要写入的配置文件。自动探测homebrew-core、homebrew-cask本地目录是否存在存在才做git remote替换不存在就跳过。持久化HOMEBREW_API_DOMAIN等环境变量到正确的shell配置文件且重复执行不会产生重复配置。替换前自动备份原始remote URL支持一条命令回滚官方源。换源完成后自动跑一次brew update做验证。同时我也明确了脚本不该做什么不负责安装Homebrew本体不处理网络链路完全不通的问题不主动清理缓存。边界想清楚脚本才不会越管越宽最后变成一团浆糊。3. 逐模块拆解脚本实现环境探测、源替换与变量持久化下面进入正题我把脚本拆成三段来讲每一段都可以单独拿来复用。3.1 环境探测版本、架构、Shell 一个都不能少脚本的第一件事是搞清楚自己运行在什么环境里。我最初写的版本偷懒直接用command -v brew定位仓库结果在一台全新Mac上压根没找到brew整个脚本直接报错退出。后来改成先探测架构再推断安装路径再回退到brew --repo逻辑就稳了。#!/usr/bin/env bash set -euo pipefail # 镜像源基础地址可通过环境变量覆盖方便切换 MIRROR_BASE${MIRROR_BASE:-https://mirrors.ustc.edu.cn} BREW_GIT_REMOTE${BREW_GIT_REMOTE:-$MIRROR_BASE/brew.git} CORE_GIT_REMOTE${CORE_GIT_REMOTE:-$MIRROR_BASE/homebrew-core.git} CASK_GIT_REMOTE${CASK_GIT_REMOTE:-$MIRROR_BASE/homebrew-cask.git} BOTTLES_DOMAIN${BOTTLES_DOMAIN:-$MIRROR_BASE/homebrew-bottles} API_DOMAIN${API_DOMAIN:-$BOTTLES_DOMAIN/api} OS_VERSION$(sw_vers -productVersion) ARCH$(uname -m) if [[ $ARCH arm64 ]]; then HOMEBREW_PREFIX/opt/homebrew else HOMEBREW_PREFIX/usr/local fi BREW_REPO${HOMEBREW_PREFIX}/Homebrew if command -v brew /dev/null 21; then BREW_REPO$(brew --repo) fi这里有个细节值得说为什么要用uname -m而不是arch命令因为Apple Silicon的Terminal里执行arch默认可能返回i386/x86_64有时候会被Rosetta环境干扰而uname -m拿到的是当前内核的真实架构判断Apple Silicon更可靠。Shell类型检测同理。macOS从Catalina开始默认Shell是zsh但你没法保证用户没有切回bash所以我做了两层判断分别对应~/.zshrc和~/.bash_profile。SHELL_RC$HOME/.zshrc case $SHELL in */bash) SHELL_RC$HOME/.bash_profile ;; */zsh) SHELL_RC$HOME/.zshrc ;; esac不写bashrc而写bash_profile是因为macOS上bash的登录Shell默认加载的是profile系列文件把环境变量塞进bashrc经常在图形界面终端里不生效。3.2 核心替换段git remote 与四个环境变量的配合环境探测完进入真正的替换逻辑。第一件事永远是备份而不是上来就改。我的做法是把当前remote URL写进一个带时间戳的临时文件回滚时直接读这个文件恢复。BACKUP_FILE/tmp/homebrew_git_backup_$(date %Y%m%d%H%M%S).txt echo $BREW_REPO $(git -C $BREW_REPO remote get-url origin 2/dev/null || echo ) $BACKUP_FILE接下来是git remote替换。这里必须根据目录是否存在做判断因为Homebrew 4.0默认安装机制下很多环境根本没有homebrew-core这个本地git目录强行执行git -C会报没有那个目录的错这也是网上不少教程抄了之后反而搞坏环境的原因。if [[ -d $BREW_REPO/.git ]]; then git -C $BREW_REPO remote set-url origin $BREW_GIT_REMOTE fi CORE_DIR$BREW_REPO/Library/Taps/homebrew/homebrew-core CASK_DIR$BREW_REPO/Library/Taps/homebrew/homebrew-cask if [[ -d $CORE_DIR/.git ]]; then git -C $CORE_DIR remote set-url origin $CORE_GIT_REMOTE fi if [[ -d $CASK_DIR/.git ]]; then git -C $CASK_DIR remote set-url origin $CASK_GIT_REMOTE fi环境变量的持久化我用的是先清理再追加策略。直接追加会导致重复执行脚本时变量堆积后面的export覆盖前面的配置看起来一团乱。用grep -q判断存在再决定是否写入逻辑更干净。grep -q set homebrew mirror by script $SHELL_RC 2/dev/null \ sed -i /# --- set homebrew mirror by script/,/^$/d $SHELL_RC { echo echo # --- set homebrew mirror by script --- echo export HOMEBREW_API_DOMAIN\$API_DOMAIN\ echo export HOMEBREW_BOTTLE_DOMAIN\$BOTTLES_DOMAIN\ echo export HOMEBREW_BREW_GIT_REMOTE\$BREW_GIT_REMOTE\ echo export HOMEBREW_CORE_GIT_REMOTE\$CORE_GIT_REMOTE\ } $SHELL_RC这里一定要提醒macOS自带的sed是BSD版本-i参数后面必须紧跟一个空字符串写成-i不带参数会直接报错。这个坑我在Linux上写脚本习惯后切回macOS踩过一次。3.3 验证与回滚脚本不是做完就跑替换完不验证等于白做。我加了两层验证第一层是探测镜像源连通性第二层是执行一次真实的brew update。HTTP_CODE$(curl -s -o /dev/null -w %{http_code} -I $BOTTLES_DOMAIN/) if [[ $HTTP_CODE ! 200 $HTTP_CODE ! 403 $HTTP_CODE ! 301 ]]; then echo WARNING: 镜像源连通性异常HTTP $HTTP_CODE fi source $SHELL_RC brew update403和301在镜像站里经常出现有的镜像根路径会返回重定向有的会返回Forbidden但不影响实际资源访问所以不能只认200。把这几个状态码都放行后误报率低很多。回滚逻辑也不复杂就是把备份文件里的remote URL逐行恢复回去同时把shell配置文件里的环境变量整段删掉。#!/usr/bin/env bash # --- 回滚模式 --- if [[ ${1:-} --rollback ]]; then LATEST_BACKUP$(ls -t /tmp/homebrew_git_backup_*.txt 2/dev/null | head -n1) if [[ -z $LATEST_BACKUP ]]; then echo 没有找到备份文件无法回滚 exit 1 fi while read -r repo url; do [[ -n $repo -n $url ]] git -C $repo remote set-url origin $url done $LATEST_BACKUP sed -i /# --- set homebrew mirror by script/,/^$/d $SHELL_RC echo 已回滚官方源请注意执行 source $SHELL_RC exit 0 fi设计回滚的初衷很朴素镜像源偶尔会抽风也可能某天你想把环境还原成官方配置。有这个入口在脚本就不再是一次性工具而是个可以持续用的维护工具。4. 实测记录脚本上线后遇到的五个真实问题脚本写出来只是开始真正有价值的坑全在实测阶段。这五个问题我一个个记录排查过程每一个都对应一种典型环境。4.1 换了core源仍然慢新版Homebrew走了API路径第一次跑完脚本我自信满满地在一台测试机上执行brew update结果依旧卡了几十秒。第一反应是不是镜像源挂了但curl直连镜像速度很快。后来用brew update --verbose查看详细输出发现它一开始请求的域名是formulae.brew.sh压根不是我设置的中科大API。原因很直接环境变量虽然写进了~/.zshrc但当前这个终端会话是在写之前就启动的环境变量根本没加载。执行source ~/.zshrc后brew config看到HOMEBREW_API_DOMAIN已经指向中科大再跑brew update瞬间就过了。这个案例说明两件事脚本里一定要加source动作或明确提示以及验证环境变量是否生效最靠谱的命令是brew config它会列出所有HOMEBREW_*变量的实际取值。另外还有一个隐藏变量值得注意HOMEBREW_INSTALL_FROM_API。新版Homebrew默认值为1走API路径。如果某些老教程或自定义配置把它显式设置为0Homebrew会强制回到git clone homebrew-core的模式那就算API域名换了也没用。我在脚本里补了一行显式导出HOMEBREW_INSTALL_FROM_API1把这条路径锁死。4.2 老系统遇上新版本this version of mac os is not supported的真相排查第二台机器时遇到的是启动报错终端直接弹出一行红字this version of mac os is not supported on this platform。这台机器是某款2015年的MacBook系统还停在Big Sur。原因是Homebrew主程序一直在往前迭代新版本对macOS的最低版本要求不断抬升老系统已经处于官方支持边界之外。这种现象和镜像源没有直接关系但恰恰是写换源脚本时必须考虑的前置条件——一个老系统连brew都无法运行时换源根本无从谈起。我的处理方式是给脚本加了一段系统版本预检if [[ $(echo $OS_VERSION | cut -d. -f1) -lt 12 ]]; then echo WARNING: 当前系统为 macOS $OS_VERSION新版 Homebrew 可能不受支持 fi注意这里只是警告不是直接退出。因为老系统用户可以手动安装旧版本Homebrew或者从已有环境迁移过来。但脚本至少要给出提示避免用户在不明不白的情况下继续执行最后被一屏报错淹没。4.3 Apple Silicon与Rosetta双brew并存时的替换陷阱第三台机器是M1 MacBook Pro问题更隐蔽。执行brew --repo得到的是/opt/homebrew路径脚本也顺利把路径替换了但用户实际在/usr/local下还装了一套x86_64的Homebrew那是当初用Rosetta终端装的。两套brew并存终端默认加载的是arm64那套脚本只处理了它。这种情况如果不处理会出现诡异的现象脚本跑完当前终端的brew确实换好源了但用户一旦用Rosetta终端打开那套老brew还是官方源依然慢成狗。我在脚本里加了一个检测如果/usr/local/Homebrew和/opt/homebrew两个目录同时存在就提示用户当前只处理激活的那一套如果需要两套都换可以显式指定路径执行。多数用户其实只需要arm64那套但至少要有知情权。顺带发现一个常见后遗症/opt/homebrew目录属主如果是rootbrew install时会出现权限报错处理方式就是sudo chown -R $(whoami) /opt/homebrew这个也写进了提示。4.4 环境变量持久化后不生效配置文件与加载时机第四个问题来自一个很日常的场景脚本写完环境变量用户打开一个新终端标签页跑brew config发现变量还是空的。我一开始怀疑是Shell配置写错了手动检查文件内容变量确实在里面。后来才发现是iTerm2的问题——它默认的新标签页不加载~/.zshrc需要设置里面打开登录Shell选项。这种情况本质上是配置文件写对了但加载时机不对。macOS终端的默认行为是login shell会加载profile相关文件但一些第三方终端模拟器或者用户手动改过启动命令可能变成非login模式~/.zshrc就不会被自动加载。脚本层面能做的有限我只能做两件事一是写入后立即source一次保证当前会话生效二是输出一行提示告诉用户如果新开终端仍然不生效检查终端是否以login shell模式运行。这个问题虽然不是脚本能根治的但提前提示能省用户大量排查时间。4.5 镜像源临时不可用如何切换备用源而不破坏配置最后一个问题不是bug而是运维场景某天下午中科大镜像站响应变得很慢brew install又开始超时。用户不知所措问我是不是要从头再跑一遍新脚本。答案是不需要。我在脚本设计时把镜像基础地址做成了环境变量切换源只需要在命令前面临时覆盖MIRROR_BASEhttps://mirrors.aliyun.com ./homebrew_mirror.sh执行完脚本内的所有${MIRROR_BASE}都会替换成阿里云地址相当于用同一个脚本完成了从A镜像切到B镜像的全过程。回滚、验证、环境变量更新照常工作。这种设计带来的额外好处是你想比较两个镜像哪个快直接跑两遍脚本再分别time brew update一次数据就出来了。我实际测过中科大和阿里云在晚高峰时段的速度差异还挺明显中科大低谷期能跑到几MB/s阿里云高峰期的延迟则更稳定一些。5. 脚本如何日常使用我的维护习惯与体会脚本跑通后落地成日常习惯的周期其实很短。我现在维护这套脚本的方式值得分享一下。第一脚本文件不再往/tmp丢而是放进~/bin目录同时纳入dotfiles仓库管理。这样换新机器时一条同步命令就能把脚本带过去。但我不太建议用网络上curl一行管道直接执行的方式分发这类脚本尤其是涉及改git remote和环境变量的操作你自己都不知道那段脚本在背后干了什么风险太高。自己维护一份逐行能看懂才是最稳的。第二使用时机总结下来就这么几个刚安装完Homebrew之后马上跑一次Homebrew大版本升级后跑一次镜像源连续超时的时候跑一次。没有必要频繁执行因为它本质上是配置调整不是常驻服务。第三也是我最近才意识到的换源脚本最怕的不是命令写错而是不知道Homebrew实际走了哪条链路。所以排查问题时我第一反应永远是看brew config确认四个HOMEBREW_*变量的实际值辅以brew update --verbose观察请求域名。只要这两条命令跑出来的结果符合预期那Homebrew慢的问题就已经排除了大半。最后再说一个边界情况镜像源不是万能的。某些通过Cask安装的软件包体本身托管在GitHub Releases里这部分流量依然走官方域名还有少量仓库不在Homebrew默认仓库里是第三方tap这类tap的clone请求也不会走你配置的core镜像。遇到这种情况不用怀疑脚本失效它是正常的——换源解决的是Homebrew经典链路问题而不是所有网络问题。四台机器全部换源完成后我最大的感受是好的脚本不是把所有操作堆在一起而是每一段都明确知道自己为什么要这么做。换源这件事本身不难难的是把新版Homebrew的API链路、不同架构的路径差异、Shell配置的加载机制全都理顺。把这套逻辑写成脚本后以后再遇到谁跟我说Homebrew慢到没法用我只需要递过去一行命令跑一下然后brew update完事。
预测建模实战：从数据到业务落地)
