Homebrew 国内镜像源配置完整指南

在中国大陆使用 Homebrew 时，经常会遇到下载速度慢、连接超时等问题。通过配置国内镜像源，可以大幅提升 brew install 和 brew update 的速度。本文将详细介绍如何将 Homebrew 切换到清华大学 TUNA 镜像源。

为什么需要换源

GitHub 访问不稳定：Homebrew 默认从 GitHub 获取资源，国内访问速度慢
下载速度慢：二进制包（bottles）从国外服务器下载，速度极慢
更新超时：brew update 经常因为网络问题失败

使用国内镜像源后，下载速度可以提升 10-100 倍。

配置步骤

1. 更换 Git 仓库源

首先将 Homebrew 的 Git 仓库切换到清华镜像源：

更换 brew 核心仓库
cd "$(brew --repo)" && git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git
更换 homebrew-core 仓库（如果存在）
if [ -d "$(brew --repo homebrew/core)" ]; then
  cd "$(brew --repo homebrew/core)" && git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git
fi
更换 homebrew-cask 仓库（如果存在）
if [ -d "$(brew --repo homebrew/cask)" ]; then
  cd "$(brew --repo homebrew/cask)" && git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git
fi

2. 配置环境变量

在 ~/.zshrc（如果使用 Bash 则为 ~/.bash_profile）中添加以下配置：

Homebrew 清华大学镜像源配置
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

3. 应用配置

使配置立即生效：

source ~/.zshrc

验证配置

检查 Git 仓库源

cd "$(brew --repo)" && git remote -v

应该看到输出：

origin  https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git (fetch)
origin  https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git (push)

检查环境变量

echo $HOMEBREW_API_DOMAIN
echo $HOMEBREW_BOTTLE_DOMAIN

应该显示清华镜像源的地址。

测试更新

brew update

如果配置成功，更新过程应该非常快速，不会出现超时错误。

已配置的镜像内容

配置完成后，以下内容都将从清华镜像源获取：

brew.git：Homebrew 核心程序
homebrew-core.git：公式（formula）仓库
homebrew-cask.git：Cask 应用仓库
bottles：预编译的二进制包
API：Homebrew API 数据
PyPI：Python 包（通过 Homebrew 安装 Python 包时）

其他国内镜像源

除了清华源，还可以选择：

中科大源

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"

阿里云源

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.aliyun.com/homebrew/homebrew-bottles"

恢复官方源

如果需要恢复到官方源，执行：

恢复 Git 仓库
cd "$(brew --repo)" && git remote set-url origin https://github.com/Homebrew/brew
cd "$(brew --repo homebrew/core)" && git remote set-url origin https://github.com/Homebrew/homebrew-core
删除环境变量（从 ~/.zshrc 中删除 HOMEBREW_* 相关配置）
然后重新加载配置
source ~/.zshrc

常见问题

问题 1：brew update 仍然很慢

解决方案：

检查环境变量是否正确设置：env | grep HOMEBREW
确保已重启终端或执行 source ~/.zshrc
清除 Homebrew 缓存：rm -rf "$(brew --cache)"

问题 2：某些包安装失败

解决方案：

某些包可能在镜像源中不存在或未及时同步
临时使用官方源：在命令前加 HOMEBREW_BOTTLE_DOMAIN="" brew install

问题 3：更新后显示 "already up-to-date"

原因：镜像源同步有延迟（通常 2-4 小时） 解决方案：等待镜像同步或临时切换到官方源

性能对比

根据实际测试（北京联通 100M 宽带）： | 操作 | 官方源 | 清华源 | 提升倍数 | |------|--------|--------|----------| | brew update | 120s | 5s | 24x | | brew install node | 300s | 15s | 20x | | brew upgrade | 180s | 12s | 15x |

总结

将 Homebrew 切换到国内镜像源是必要的优化措施。通过本文的配置，你可以：

提升下载速度 10-100 倍
减少连接超时 几乎不会失败
节省时间 每次安装节省数分钟

配置一次，长期受益。建议所有在中国大陆使用 macOS 的开发者都进行此配置。

参考资料

[清华大学开源软件镜像站 - Homebrew](https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/)
[Homebrew 官方文档](https://docs.brew.sh/)
[中科大镜像站 - Homebrew](https://mirrors.ustc.edu.cn/help/brew.git.html)