---
url: https://eoht.net/fe/homebrew/mirror-source.md
description: 区分 Homebrew API、bottles 和 Git 仓库的镜像设置，按镜像站说明配置、验证，并恢复官方默认源。
---

# Homebrew 镜像配置：API、安装包与 Git 仓库 {#homebrew-mirror-configuration}

Homebrew 的软件元数据、预编译安装包（bottles）和自身 Git 仓库分别使用不同入口。仅修改 Git remote 不会同时切换所有下载。镜像的同步与覆盖范围由镜像站决定，软件自身的下载地址也不一定被镜像。

以下适用于 Bash / zsh。先在当前终端测试一组配置，确认可用后再将对应的 `export` 行加入自己的 shell 启动文件；不要同时启用多个镜像站。

## 使用中科大的镜像 {#use-ustc-homebrew-mirror}

按[中科大 Homebrew 镜像说明](https://mirrors.ustc.edu.cn/help/brew.git.html)设置：

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

常规 API 安装不需要本地 `homebrew/core` 克隆。只有已显式使用 Git tap、并且 `brew tap` 列出了 `homebrew/core` 时，才按镜像站说明额外配置其 remote：

```sh
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
```

不要为切换镜像而假定 `Library/Taps/homebrew/homebrew-core` 必然存在。

## 使用清华大学的镜像 {#use-tsinghua-homebrew-mirror}

清华镜像的 API、bottles 和 Git 入口请以[清华 Homebrew 镜像帮助](https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/)为准。选择该站时应成组替换上一节的环境变量，并按实际存在的 tap 配置 Git remote；不要沿用旧教程只修改 `homebrew-core` 的做法。

## 验证与恢复默认源 {#verify-and-restore-homebrew-mirrors}

```sh
brew config
brew update
brew info wget
```

检查 `brew config` 中的镜像环境变量和 Git remote；`brew update` 成功只说明更新过程完成，不能证明每个软件的安装包都能下载。安装或升级具体软件时仍需观察实际下载来源和错误。

恢复默认前，先从 shell 启动文件删除自行添加的镜像环境变量，然后在当前终端执行：

```sh
unset HOMEBREW_BREW_GIT_REMOTE HOMEBREW_API_DOMAIN HOMEBREW_BOTTLE_DOMAIN
git -C "$(brew --repo)" remote set-url origin https://github.com/Homebrew/brew
brew update
```

若曾修改已有 `homebrew/core` 的 remote，再单独恢复：

```sh
git -C "$(brew --repo homebrew/core)" remote set-url origin https://github.com/Homebrew/homebrew-core
```

其他 tap 或额外镜像变量也需按自己的改动恢复；重新打开终端后再运行 `brew config` 检查。