Apple Silicon Mac配置Homebrew中科大镜像源

国内直连 GitHub 装 Homebrew 经常超时，本文针对 Apple Silicon Mac（默认路径 /opt/homebrew）讲如何配置中科大镜像源。

⚠️ 关键变化：Homebrew 4.0 之后改用 JSON API 获取仓库信息，中科大从 2026 年 6 月起已不再提供 homebrew-core.git 镜像。新版配置的核心是 HOMEBREW_API_DOMAIN + HOMEBREW_BOTTLE_DOMAIN，不要再设 HOMEBREW_CORE_GIT_REMOTE，否则环境会被搞坏。

一、安装 Homebrew

未安装的用户，先设镜像环境变量，再用中科大安装脚本：

export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"

/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"

完成后注入 shell 环境（Apple Silicon）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

二、配置镜像源

编辑 ~/.zshrc，在开头加入：

export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"

四个变量缺一不可：

• HOMEBREW_API_DOMAIN：formula 元数据 API 加速（brew 4.0+ 核心）
• HOMEBREW_BOTTLE_DOMAIN：预编译包（bottle）下载加速
• HOMEBREW_BREW_GIT_REMOTE：Homebrew 本体 git 仓库镜像
• HOMEBREW_INSTALL_FROM_API=1：强制使用 API 模式

生效：

source ~/.zshrc

三、验证

brew config | grep -E "API_DOMAIN|BOTTLE_DOMAIN|BREW_GIT"

输出应包含三条对应中科大的地址。再跑 brew update、brew --version，不再卡在克隆仓库或下载 metadata 即说明生效。

四、Intel Mac 差异

路径改为 /usr/local/bin/brew，镜像环境变量完全一致：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc

五、排错

• brew update 卡在 Cloning homebrew-core：删掉无效的 HOMEBREW_CORE_GIT_REMOTE 变量即可。
• bottle 下载慢：检查 HOMEBREW_BOTTLE_DOMAIN 拼写，或临时改用清华源。
• 安装时 Ruby 栈报错：Homebrew 本体过旧，清理后重装。

六、推荐的 .zshrc 顺序

镜像变量放最前，brew shellenv 放其后：

# 镜像环境变量（最前）
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"

# brew 自身环境
eval "$(/opt/homebrew/bin/brew shellenv zsh)"

七、备用镜像

中科大不稳定时，替换 HOMEBREW_BOTTLE_DOMAIN 即可，其余不变：

未经允许不得转载：编源视界 » Apple Silicon Mac配置Homebrew中科大镜像源