最近在帮朋友收拾一台吃灰的 Mac，重新配开发环境，第一步就卡在 Homebrew 上。官方 install.sh 跑了大半天，最后弹出一串 “fatal: unable to access”、“Failed during: git fetch” 之类的报错，整个终端窗口一片红。经过反复排查，最终发现所有问题都指向同一个根源——安装脚本要访问的几个国外地址不稳定。把下载源换成国内镜像之后，一台机器基本十几分钟就装完了。这篇就把整个排查过程、镜像配置方法和踩过的坑完整写出来。
1. 为什么 brew 安装总失败：先找卡点再动手
1.1 Homebrew 安装过程的三个网络依赖
很多人一遇到 brew 安装失败，第一反应是“换个网络重试”，换完还是失败，然后开始怀疑虚拟机、怀疑系统、怀疑人生。其实 Homebrew 的安装过程非常简单，就是“下载脚本 + 拉取仓库 + 下载预编译包”，但每一步都依赖特定的远端服务器，而这些服务器在国内的连通性差异极大：
| 安装步骤 | 访问地址 | 占用的功能 | 典型失败现象 |
|---|---|---|---|
| 下载官方安装脚本 | raw.githubusercontent.com | install.sh 本体 | curl: (7) Failed to connect |
| 克隆 brew 本体仓库 | github.com/Homebrew/brew | Homebrew 的程序本体 | fatal: unable to access |
| 克隆 homebrew-core 仓库 | github.com/Homebrew/homebrew-core | 软件源索引、历史公式 | remote: Repository not found |
| 下载预编译 bottle 包 | ghcr.io / formulae.brew.sh | 软件安装时的二进制包 | curl: (35) LibreSSL SSL_connect |
| 获取 API 元数据 | formulae.brew.sh | Homebrew 4.x 的 JSON API | Error: JSON_DOMAIN 超时 |
你看到的 “curl: (7) Failed to connect”，多半是第一步卡住了；看到 “git clone ... into /opt/homebrew”，是第二步卡住了；看到 “Error: Download failed” 是第三、四步卡住了。不同报错指向不同环节，先定位具体卡在哪一步，再对症下药。
1.2 镜像方案的原理其实很简单
“国内镜像”这四个字听起来很玄乎，本质上就是把这些远端 URL 替换成国内高校、云厂商提供的同步仓库。Homebrew 本身是开源程序，国外有人同步全量数据，国内也有平台同步全量数据。你的电脑不再去访问 GitHub、ghcr.io，而是访问国内镜像站，速度和稳定性自然就上来了。
Homebrew 提供了几个现成的环境变量来支持这个替换，这是它官方设计的一部分，不是野路子：
HOMEBREW_BREW_GIT_REMOTE：brew 本体仓库地址HOMEBREW_CORE_GIT_REMOTE：homebrew-core 仓库地址（主要是老版本 Homebrew 需要）HOMEBREW_API_DOMAIN：Homebrew 4.x 的 JSON API 下载域名HOMEBREW_BOTTLE_DOMAIN：预编译二进制包的下载域名HOMEBREW_PIP_INDEX_URL：Python 包的索引地址，类似国内 pip 源
把这几个变量指向国内镜像站，再用官方安装脚本执行安装，脚本会严格尊重这些变量，全程不走 GitHub。这种方式比“先装完再换源”更省事，因为你不需要在安装完之后再去改仓库地址。
1.3 选哪个镜像源：三个主流镜像的对比
我用过的镜像里，比较稳定的是清华 TUNA、阿里云和中科大。三者同步速度、更新频率都在可接受范围内，决定选哪个主要看你所在的网络环境和习惯：
| 镜像站 | brew 仓库地址 | API / bottle 地址 | 特点 |
|---|---|---|---|
| 清华 TUNA | mirrors.tuna.tsinghua.edu.cn/git/homebrew | mirrors.tuna.tsinghua.edu.cn/homebrew-bottles | 更新较快，文档齐全，支持安装脚本镜像 |
| 阿里云 | mirrors.aliyun.com/homebrew | mirrors.aliyun.com/homebrew-bottles | 国内机房线路好，云厂商维护，容量大 |
| 中科大 | mirrors.ustc.edu.cn/brew.git | mirrors.ustc.edu.cn/homebrew-bottles | 老牌高校源，稳定性好 |
我强烈建议不要同时混用多个源的地址，比如 brew 仓库用清华、bottle 域名用中科大。镜像站的同步频率不一样，某些版本包可能在 A 站有、B 站还没跟上，混用容易出现 “No bottle available” 这种奇怪的问题。选定一个源，全部走一个。
2. 安装前的准备：这五分钟能帮你避开大部分坑
2.1 确认 macOS 版本与处理器架构
镜像安装法的核心步骤对所有 macOS 版本基本一致，但不同处理器的安装路径完全不同，最好一开始就确认清楚。
Intel Mac 的 Homebrew 默认装在/usr/local，Apple Silicon（M 系列芯片）的 Mac 装在/opt/homebrew。安装脚本会自动判断，但你手动配置环境变量时要注意架构相关的内容，比如/opt/homebrew/bin比/usr/local/bin在 PATH 里的优先级问题。
另一个容易被忽略的点是 Homebrew 对系统版本的要求。Homebrew 会逐步放弃对旧 macOS 的支持，某些版本明确要求 macOS 12 以上，甚至更高的系统版本。如果你的 Mac 版本较老，安装时可能遇到类似 “Your macOS version is unsupported” 的提示。遇到这种情况，比较靠谱的办法是安装历史版本的 Homebrew，而不是硬刚最新版。我的建议是先去“系统设置 - 通用 - 关于”确认系统版本，再决定用哪个方案。
2.2 清理残留的 Homebrew
很多人的 Mac 之前装过 Homebrew，但安装中途失败或手动删除过，导致系统里残留半成品的目录和文件。残留文件对重新安装会造成致命的干扰，症状通常是：
- 安装脚本报错 “Directory not empty: /opt/homebrew”
- 提示 “Failed to clone ... already exists”
- brew 命令能执行但又缺库，一直报错
我建议在正式安装前先检查一下：
# 查看当前是否有 brew 命令 which brew # 查看常见的安装目录是否存在 ls -la /opt/homebrew 2>/dev/null ls -la /usr/local/Homebrew 2>/dev/null # 查看安装目录下的关键文件 ls /usr/local/Homebrew/bin/brew 2>/dev/null ls /opt/homebrew/bin/brew 2>/dev/null如果有残留，简单粗暴删掉通常最有效。比如：
# Intel Mac sudo rm -rf /usr/local/Homebrew sudo rm -rf /usr/local/Caskroom sudo rm -rf /usr/local/Cellar sudo rm -rf /usr/local/etc sudo rm -rf /usr/local/opt sudo rm -rf /usr/local/var # Apple Silicon Mac sudo rm -rf /opt/homebrew这里我再补充一个更稳妥的操作：如果之前正常装过 Homebrew 而且里面有不少软件包，不要直接删目录，先用brew list --formula > ~/brew-formulas.txt把已安装的软件列表导出来，等新环境装好后根据列表批量重装。这个操作花不了三十秒，能避免删完才发现需要的工具没记录的尴尬。
2.3 确认 Command Line Tools 是否就绪
Homebrew 安装时依赖 Apple 的 Command Line Tools（命令行开发者工具），系统里没有它，安装脚本会中途停下。很多生手在这一步就卡住，因为它和 Homebrew 本身没有直接关系，报错信息却特别像 Homebrew 的问题。
检查方法：
xcode-select -p如果输出的是/Library/Developer/CommandLineTools，说明已经正常安装。如果报错找不到路径，就先安装：
xcode-select --install系统会弹出一个图形窗口，点“安装”就行。这个过程需要下载约 1GB 左右的组件，完全走 Apple 官方 CDN，速度通常还可以。如果弹窗一直不出现或者安装反复失败，可以到 Apple Developer 官网下载对应的 Command Line Tools 安装包，找到与 macOS 版本匹配的那个安装包，安装完成后再继续。
2.4 先测连通性，别让镜像白忙活
用镜像安装并不能保证 100% 成功，前提是镜像站本身能连通。我见过不少人配好了镜像，最后还是失败，因为学校/公司的网络直接屏蔽了某些地址，或者镜像站在当地被限速。建议先把测试命令跑一遍：
# 测试镜像站连通性 curl -I https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles # 测试 cd到 brew 仓库是否可访问 curl -I https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git/info/refs # 测试能够访问 GitHub 官方脚本（备用） curl -I https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh第一个和第二个测试能通，说明镜像网没问题。第三个能通最好，不能通也不怕，后面有用镜像站下载安装脚本的替代方法。
3. 国内镜像安装完整实操：从零到可用
3.1 设置环境变量并下载官方安装脚本
我推荐的最小化配置是这一组，以清华 TUNA 镜像为例：
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_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"贴到终端里，回车。等下安装脚本时，这些变量会直接传给脚本使用。
接着下载安装脚本。优先用官方脚本，因为它的逻辑最完整、版本最新：
curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o ~/install-brew.sh如果这一步连不上 raw.githubusercontent.com，就改从清华镜像下载 install 脚本：
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/Homebrew/install.sh -o ~/install-brew.sh以上两条任选其一。下载完之后我先不急着执行，先检查一下脚本内容是否完整：
head -20 ~/install-brew.sh wc -l ~/install-brew.shinstall.sh 通常有几万行，如果只有几十行，说明下载不完整，直接再次下载。
3.2 执行安装脚本并观察关键输出
执行安装：
/bin/bash ~/install-brew.sh脚本运行后会做这些事：先检查系统版本和已安装依赖，再确认 Xcode Command Line Tools，然后会问你 “Press RETURN to continue or any other key to abort”。回车继续。
接下来会看到类似这样日志：
Downloading and installing Homebrew... HEAD is now at 1a2b3c4d5 更新到 ... ==> Migrating /usr/local/var to /usr/local/var... ==> Already installed: git这里需要留意两个关键点。第一，出现git clone ... https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git这类日志，说明镜像变量确实生效了；如果我第一注意里面还是github.com/Homebrew/brew.git，那说明环境变量没当前终端会话中导入或权限不对，趁早 Ctrl+C 再排查。第二，看到Downloading ... formula或者Fetching bottle关键字，说明后面安装软件时也会走镜像，不仅是 Homebrew 本体。
安装过程整体比较快，快的话几分钟，慢的话十几分钟。如果长时间停留在某一步毫无进展，可以先等五分钟，镜像站和 GitHub 不通本质上是不同的，但大量仓库 clone 比较吃带宽。
3.3 安装完成后的环境变量配置
安装脚本结束时会提示你把 brew 加入 PATH。Apple Silicon Mac 可以这样写：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"Intel Mac 通常是：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile eval "$(/usr/local/bin/brew shellenv)"然后验证：
brew --version能显示Homebrew 4.x.x就说明安装成功了。这时候再给 Shell 加上刚才那几个镜像环境变量，不然下次启动终端后镜像配置就丢了，brew install还是会回到国外源：
cat >> ~/.zshrc <<'EOF' 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_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_NO_AUTO_UPDATE=1 EOF source ~/.zshrcHOMEBREW_NO_AUTO_UPDATE=1是我个人强烈建议加的，它表示每次安装软件时不让 Homebrew 自动跑brew update。自动更新本身很占时间，在镜像环境下还会额外拉取大量更新数据，日常使用关掉能让你的brew install快一倍以上，需要更新时手动执行brew update就够了。
3.4 已装好但是网络卡的补救改源法
如果你手上这台 Mac 的 Homebrew 已经装好，但每次安装软件都龟速，不用重装，直接改仓库地址就行：
# 定位安装路径 # Apple Silicon: cd /opt/homebrew # Intel: cd /usr/local/Homebrew # 查看原始的远端地址 git remote -v然后逐一把 GitHub 地址改为国内镜像：
git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.githomebrew-core 目录（如果存在）同理：
cd /opt/homebrew/Library/Taps/homebrew/homebrew-core git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git改完后再加环境变量（同 3.3 中的 zshrc 配置），执行一次brew update，之后安装软件的下载瓶颈就解决了。
4. 常见问题与排错速查：我遇到过的每个坑
4.1 安装脚本卡在 “Generating a formula” 或 “Downloading ..."
这种情况十次里有八次是在下载 API 元数据时超时。Homebrew 4.x 默认通过HOMEBREW_API_DOMAIN拉取全量 JSON 索引，而不是直接 clone 整个 core 仓库。如果这个变量没配，或者配错了尺寸对，就会卡住。
先检查环境变量是否有望：
env | grep HOMEBREW如果 API 域名为空，重新 exportHOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN，再继续。另外强烈建议首次安装不要在最开始就执行brew update，等brew --version能正常输出了再更新，否则脚本会先试图拉取远程索引，自找麻烦。
4.2 提示 “Directory not empty” 或 “Already exists”
这是典型的残留问题。安装路径里已有/opt/homebrew或/usr/local/Homebrew目录，脚本拒绝覆盖。处理办法就是我前面建议的先删除残留，再重新跑。需要注意，如果你之前是用 sudo 创建的目录，删除时也需要 sudo。
4.3 提示 “Error: Command Line Tools are not installed”
先执行xcode-select -p，如果没有 React Native 之类的，确认。xcode-select --install之后弹窗没有出现，多半是系统已经装过或者缓存了旧安装记录，可以用sudo rm -rf /Library/Developer/CommandLineTools强制清掉再试一次。这个方法仅适用于确实没有在用 Xcode 工具链的情况，虽然有些粗暴，但我踩过两次坑后实测确实有效。
4.4 curl 提示 “SSL certificate problem”
比较少见，但确实遇到过。原因通常是系统时间不对，证书校验失败。检查系统时间、时区，破解同步后重新执行。如果是公司网络的中间人证书拦截，镜像也救不了，需要换一个网络环境尝试。
4.5 安装成功后 brew 命令报 “Permission denied”
新生成的/opt/homebrew下有些文件权限故意收紧，不属于当前用户。最根本的方法是确保安装脚本是用你的普通用户身份执行的，而不是 sudo。如果已经装了且权限不对，可以修权一下：
sudo chown -R $(whoami) /opt/homebrewIntel 路径同理，但注意不要对整个/usr/local执行 chown，那里还有很多系统组件。
4.6 常见报错速查表
| 症状 | 根因 | 对策 |
|---|---|---|
| curl: (7) Failed to connect | 无法访问远端 | 改用镜像下载脚本，或检查镜像连通性 |
| fatal: Could not read from remote repository | git 仓库拉取失败 | 确认 HOMEBREW_BREW_GIT_REMOTE 生效 |
| Error: TLS certificate verification failed | 证书校验失败 | 同步系统时间；若公司网络拦截则更换网络 |
| No such file or directory: /opt/homebrew/bin/brew | 装错路径，或没配 PATH | 确认架构，配置 zprofile 后重新打开终端 |
| Failed to link /usr/local/lib/... | 文件冲突 | 用 brew cleanup 或手动解除冲突软链 |
Error: Thebrewbinary is not in PATH | 安装完成但没写入配置 | echo eval 命令写入 ~/.zprofile 并 source |
| Your macOS version is unsupported | 系统版本太老 | 搜索历史版本 Homebrew，或升级系统 |
5. 走位于镜像方案的后期维护建议
最后聊点我的个人习惯。镜像方案装好 Homebrew 之后，日常维护不能完全放任不管。因为镜像站同步总会有一两天延迟，尤其是新发布的版本，偶尔会碰到镜像站已经更新但清华镜像却显示 404 的情况。遇到这种问题，我会临时改用阿里云的源试一次，基本上就能解决。
其次，brew update不要完全不跑，但也不要每次安装都让它自己跑。我一般固定在每周某个时间手动跑一次brew update && brew upgrade，因为 brew 源更新频繁，不更新容易出现安装时提示 “版本冲突” 的莫名问题。关闭自动更新以后，手动更新的节奏就足够让 brew 保持健康了。
另外，如果你后续需要使用 teatime 新增的像brew services管理后台服务这类功能，需要单独补充 homebrew-services 镜像配置，因为 services 仓库也在 Git仓库体系里，默认不走 bottle 域名。配置方式与 core 仓库类似，从清华镜像拉取homebrew-services.git的地址后 git remote 指过去即可。
最后一个小提醒：安装过程中如果看到某个术语完全无从下手，不用太担心，很大概率是你不常碰的旧架构。我这套流程在 Intel 和 Apple Silicon 的十几台 Mac 上都跑通过，核心就是把环境变量这步别省，把残留目录清干净，然后让安装脚本安静跑完。剩下的就是花几分钟把 brew 用到顺手了。
