Mac Homebrew 更新卡住怎么办？如何更换国内源、查看进度和安装软件

一、问题现象

在 Mac 上使用 Homebrew 安装软件时，经常会遇到这种情况：

bash brew install php

或者：

bash brew update

终端一直停在：

bash ==> Auto-updating Homebrew...

或者：

bash ==> Updating Homebrew...

看起来像卡住了一样，等很久也没有明显进度。

这种情况通常不是命令错了，而是 Homebrew 正在连接 GitHub 或下载索引文件。由于网络原因，可能会非常慢。

二、Homebrew 为什么会卡住？

Homebrew 默认会从 GitHub 拉取更新信息，比如：

text Homebrew 主程序 Homebrew 软件源信息软件包索引 bottles 预编译安装包第三方 tap

如果网络访问 GitHub 很慢，就容易卡住。

常见卡住位置有：

bash ==> Auto-updating Homebrew...

bash ==> Updating Homebrew...

bash Checking if we need to fetch /opt/homebrew...

bash Checking if we need to fetch formula.jws.json...

bash Checking if we need to fetch /opt/homebrew/Library/Taps/xxx...

三、先判断是不是卡死

如果终端一直没输出，不一定代表卡死。

可以先等 3～5 分钟。

如果想看更详细的执行过程，可以使用：

bash brew update --verbose

如果还想看更详细的调试信息，可以使用：

bash brew update --debug

其中最常用的是：

bash brew update --verbose

它会显示 Homebrew 当前正在更新哪个仓库、哪个 tap、哪个索引文件。

四、如果真的卡住了怎么办？

如果等了很久还是不动，可以按：

bash Ctrl + C

中断当前命令。

然后可以选择：

更换 Homebrew 国内源；
跳过自动更新，直接安装软件；
移除卡住的第三方 tap；
使用 --verbose 查看具体卡在哪里。

五、查看当前 Homebrew 源

先查看 Homebrew 主仓库地址：

bash git -C "$(brew --repo)" remote -v

如果看到类似：

bash origin https://github.com/Homebrew/brew.git (fetch) origin https://github.com/Homebrew/brew.git (push)

说明当前还是官方 GitHub 源。

如果已经换成清华源，会看到类似：

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

如果已经换成中科大源，会看到类似：

bash origin https://mirrors.ustc.edu.cn/brew.git (fetch) origin https://mirrors.ustc.edu.cn/brew.git (push)

六、更换 Homebrew 源

方案一：更换为清华源

执行：

bash git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

然后查看是否成功：

bash git -C "$(brew --repo)" remote -v

如果输出里出现：

bash https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

说明主仓库已经切换成功。

方案二：更换为中科大源

如果清华源还是慢，可以换成中科大源：

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

然后查看是否成功：

bash git -C "$(brew --repo)" remote -v

如果输出里出现：

bash https://mirrors.ustc.edu.cn/brew.git

说明切换成功。

七、设置 bottles 下载源

Homebrew 安装软件时，很多软件会下载预编译包，也就是 bottles。

如果只换了 brew 主仓库，但 bottles 还是官方地址，安装软件时依旧可能很慢。

使用中科大 bottles 源

如果你使用的是 zsh，Mac 默认一般就是 zsh，可以执行：

bash echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"' >> ~/.zshrc echo 'export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"' >> ~/.zshrc source ~/.zshrc

验证是否生效：

bash echo $HOMEBREW_BOTTLE_DOMAIN echo$ HOMEBREW_API_DOMAIN

如果输出类似：

bash https://mirrors.ustc.edu.cn/homebrew-bottles https://mirrors.ustc.edu.cn/homebrew-bottles/api

说明配置成功。

使用清华 bottles 源

也可以设置清华源：

bash echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc source ~/.zshrc

验证：

bash echo $HOMEBREW_BOTTLE_DOMAIN echo$ HOMEBREW_API_DOMAIN

八、更新 Homebrew

更换源后，可以执行：

bash brew update

如果想看到详细进度，推荐执行：

bash brew update --verbose

如果看到类似下面内容，说明它已经开始正常更新了：

bash Checking if we need to fetch /opt/homebrew... ==> Updating Homebrew... Fetching /opt/homebrew... Updating /opt/homebrew... Current branch stable is up to date. Checking if we need to fetch formula.jws.json...

这说明不是卡死，而是在更新索引或检查数据。

九、跳过自动更新，直接安装软件

有时候我们的目标只是安装某个软件，不一定非要先更新 Homebrew。

比如安装 PHP：

bash brew install php

如果它自动更新很慢，可以用下面命令跳过自动更新：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php

如果要安装 PHP 8.1：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php@8.1

安装完成后查看版本：

bash php -v

十、安装指定版本 PHP

如果项目使用 Docker 里的：

text php:8.1-fpm-alpine

那么本机更推荐安装 PHP 8.1：

bash brew install php@8.1

如果更新太慢，就执行：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php@8.1

安装完成后检查：

bash php -v

如果提示找不到 php，可以执行：

bash brew link php@8.1 --force --overwrite

然后重新打开终端，再执行：

bash php -v

十一、homebrew/core 目录不存在怎么办？

有时候网上教程会让你执行：

bash git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git

但是可能会报错：

bash fatal: cannot change to '/opt/homebrew/Library/Taps/homebrew/homebrew-core': No such file or directory

这个不一定是问题。

新版 Homebrew 可能没有单独 clone homebrew/core 目录，它更多是通过 API 获取软件信息。

遇到这个报错时，可以先不用管 homebrew/core，重点确认主仓库是否切换成功：

bash git -C "$(brew --repo)" remote -v

如果主仓库已经是国内源，就可以继续：

bash brew update --verbose

或者直接跳过更新安装软件：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install 软件名

十二、第三方 tap 导致更新慢怎么办？

如果执行：

bash brew update --verbose

时看到类似：

bash Checking if we need to fetch /opt/homebrew/Library/Taps/sunnyyoung/homebrew-tap...

说明你本机安装过第三方 tap。

如果某个第三方 tap 很慢，也可能导致 Homebrew 更新卡住。

可以查看当前有哪些 tap：

bash brew tap

如果确定某个 tap 不再需要，可以移除：

bash brew untap tap名称

例如：

bash brew untap sunnyyoung/tap

注意：不要随便删除自己还在用的 tap。可以先查一下这个 tap 是做什么的，再决定是否移除。

十三、常用命令整理

查看 Homebrew 版本

bash brew -v

查看 Homebrew 主仓库位置

bash brew --repo

查看 Homebrew 当前源

bash git -C "$(brew --repo)" remote -v

更新 Homebrew

bash brew update

显示详细更新进度

bash brew update --verbose

显示调试信息

bash brew update --debug

检查 Homebrew 环境问题

bash brew doctor

更新已安装的软件包

bash brew upgrade

跳过自动更新安装软件

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install 软件名

例如：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php@8.1

查看已安装软件

bash brew list

查看当前 tap

bash brew tap

移除不需要的 tap

bash brew untap tap名称

十四、推荐处理流程

如果遇到 brew update 或 brew install 卡住，可以按下面流程处理：

第一步：中断当前命令

bash Ctrl + C

第二步：查看当前源

bash git -C "$(brew --repo)" remote -v

第三步：切换国内源

清华源：

bash git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

或者中科大源：

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

第四步：设置 bottles 和 API 源

以中科大为例：

第五步：查看更新进度

bash brew update --verbose

第六步：如果还是慢，跳过更新直接安装

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install 软件名

例如：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php@8.1

十五、恢复官方源

如果以后想恢复 Homebrew 官方源，可以执行：

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

然后编辑 ~/.zshrc，删除或注释掉下面几行：

bash export HOMEBREW_BOTTLE_DOMAIN="..." export HOMEBREW_API_DOMAIN="..."

保存后执行：

bash source ~/.zshrc

再更新：

bash brew update --verbose

十六、总结

Homebrew 卡住大多数是网络问题，不一定是命令错误。

常用解决思路是：

text 1. 用 Ctrl + C 中断卡住的命令 2. 用 brew update --verbose 查看具体进度 3. 更换 Homebrew 国内源 4. 设置 bottles 和 API 下载源 5. 如果只是安装软件，可以用 HOMEBREW_NO_AUTO_UPDATE=1 跳过自动更新 6. 如果第三方 tap 卡住，可以考虑移除不需要的 tap

最常用的安装命令是：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install 软件名

例如安装 PHP 8.1：

bash HOMEBREW_NO_AUTO_UPDATE=1 brew install php@8.1

这样可以避免每次安装软件时都被自动更新卡住。