在 macOS 或 Linux 上运行 brew install 时如果长时间卡住，盲目换源往往只能解决一半问题。因为 brew install 实际上包含 三个不同的网络阶段，不同阶段卡顿的原因和解决办法并不相同。
一、 先看症状：brew install 卡在哪一步？
| 终端卡住时的提示信息 | 所属阶段 | 慢的原因 | 对应解决方案 |
|---|---|---|---|
Auto-updating Homebrew... 或 Fetching ... |
1. 更新元数据与自身仓库 | 从 GitHub 拉取 brew.git 或公式索引 JSON 慢；或者旧版残留了庞大的 homebrew-core 本地 Git 仓库 |
方案一（配 API 与 Git 镜像）+ 方案二（清理旧仓库） |
Downloading https://ghcr.io/v2/homebrew/core/... |
2. 下载预编译二进制包（Bottles） | 命令行工具（Formula）预编译包默认托管在 GitHub Packages (ghcr.io)，国内直连极慢 |
方案一（配 HOMEBREW_BOTTLE_DOMAIN 镜像） |
Downloading https://github.com/.../releases/... 或各软件官网链接 |
3. 下载桌面软件（--cask）或源码包 |
国内镜像站只缓存命令行工具（Bottles），不缓存 Cask 桌面软件（如 Chrome、VS Code 等 .dmg/.pkg），仍需从软件官网直连下载 |
方案三（为终端挂载本地代理） |
二、 方案一：配置中科大镜像源（解决更新慢 + 命令行包下载慢）
自 Homebrew 4.0 起，官方默认通过 JSON API 获取软件包信息，不再需要克隆庞大的 homebrew-core 仓库。只需通过 3 个环境变量 即可同时加速「元数据索引」、「预编译包（Bottles）」与「Homebrew 自身更新」。
1. 临时生效（在当前终端测试）
复制以下命令到终端执行（仅对当前终端窗口生效，以安装 wget 为例）：
# 1. 加速 JSON 元数据索引（Homebrew 4.0+ 核心加速项）
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
# 2. 加速预编译二进制包（Bottles）下载
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
# 3. 加速 Homebrew 自身主仓库（brew.git）更新
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
# 测试更新与安装
brew update
brew install wget
提示：中科大镜像站目前还提供基于 OCI 结构的
HOMEBREW_ARTIFACT_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"（处于测试阶段），日常稳定使用配置上面的HOMEBREW_BOTTLE_DOMAIN即可，二者不要同时混用。详见 中科大 Homebrew Bottles 帮助 与 Homebrew 仓库帮助。
2. 永久保存配置（写入 ~/.zshrc）
确认上面速度理想后，将这 3 个环境变量写入 Shell 配置文件（macOS 默认使用 zsh，配置文件为 ~/.zshrc；若使用 bash 则改为 ~/.bash_profile 或 ~/.bashrc）。
如果之前从未配置过，可直接运行以下命令追加并生效：
cat >> ~/.zshrc << 'EOF'
# Homebrew 中科大镜像源配置
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"
EOF
source ~/.zshrc
brew update
注意：如果之前已经在
~/.zshrc中写过同名变量，请用编辑器（如open -e ~/.zshrc或nano ~/.zshrc）直接修改原有行，避免多次重复追加。配置生效后，可通过brew config查看HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN和ORIGIN是否均已指向mirrors.ustc.edu.cn。
三、 方案二：清理旧版遗留的本地 Tap 仓库（解决老用户 brew update 极慢）
如果你的 Mac 是从较早版本的 Homebrew 升级上来的，本地可能还存留着完整的 homebrew/core 和 homebrew/cask Git 仓库（体积往往超过 1GB，包含数十万次提交）。
在 Homebrew 4.0+ 已改用 JSON API 的情况下，保留这两个本地 Git 仓库不仅毫无必要，还会在每次运行 brew update 时强制执行耗时的 git fetch。
先查看当前已挂载的仓库：
brew tap
如果输出中包含 homebrew/core 或 homebrew/cask，直接将它们卸载即可（不会影响任何已安装的软件）：
brew untap homebrew/core
brew untap homebrew/cask
清理后再运行 brew update，耗时通常会从几分钟缩短到 1～2 秒。
四、 方案三：使用终端代理与临时救急（解决 --cask 桌面软件下载慢）
1. 为单次安装挂载本地代理（针对 --cask 软件或 GitHub Release）
安装 GUI 桌面软件（例如 brew install --cask google-chrome）或必须从 GitHub Releases 拉取资源的软件时，国内镜像源无法覆盖这些第三方下载地址。若本地已开启代理软件（假设 HTTP 代理端口为 7890），可在命令前临时指定代理环境变量：
https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 brew install --cask visual-studio-code
2. 单次安装临时跳过自动更新
如果急需安装某个工具，不想等待前期的 Auto-updating Homebrew... 检查，可仅对当前命令临时禁用自动更新：
HOMEBREW_NO_AUTO_UPDATE=1 brew install wget
建议：不要把
HOMEBREW_NO_AUTO_UPDATE=1长期写死在~/.zshrc中，否则本地软件包索引长期不更新，后续安装新软件时容易因依赖版本过旧而报 404 错误。
五、 附：如何干净地恢复官方默认源？
当网络环境改善或不再需要国内镜像时，请严格按以下顺序恢复（注意：必须先删配置文件并 unset 环境变量，再重置 Git 远端，否则运行 brew update 时 HOMEBREW_BREW_GIT_REMOTE 会自动把远端改回镜像站）：
第一步：删除配置文件中的镜像变量 打开
~/.zshrc（或~/.bash_profile），删除之前添加的HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN、HOMEBREW_BREW_GIT_REMOTE（及可能存在的HOMEBREW_ARTIFACT_DOMAIN）配置行并保存。第二步：清除当前终端会话中的环境变量
unset HOMEBREW_API_DOMAIN HOMEBREW_BOTTLE_DOMAIN HOMEBREW_ARTIFACT_DOMAIN HOMEBREW_BREW_GIT_REMOTE
- 第三步：将 Homebrew 主仓库远端重置回 GitHub 官方地址并更新
git -C "$(brew --repo)" remote set-url origin https://github.com/Homebrew/brew
brew update
- 第四步：检查状态是否正常
brew config
brew doctor
还没有可见的评论。