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)