最近在帮朋友收拾一台吃灰的 Mac重新配开发环境第一步就卡在 Homebrew 上。官方 install.sh 跑了大半天最后弹出一串 “fatal: unable to access”、“Failed during: git fetch” 之类的报错整个终端窗口一片红。经过反复排查最终发现所有问题都指向同一个根源——安装脚本要访问的几个国外地址不稳定。把下载源换成国内镜像之后一台机器基本十几分钟就装完了。这篇就把整个排查过程、镜像配置方法和踩过的坑完整写出来。1. 为什么 brew 安装总失败先找卡点再动手1.1 Homebrew 安装过程的三个网络依赖很多人一遇到 brew 安装失败第一反应是“换个网络重试”换完还是失败然后开始怀疑虚拟机、怀疑系统、怀疑人生。其实 Homebrew 的安装过程非常简单就是“下载脚本 拉取仓库 下载预编译包”但每一步都依赖特定的远端服务器而这些服务器在国内的连通性差异极大安装步骤访问地址占用的功能典型失败现象下载官方安装脚本raw.githubusercontent.cominstall.sh 本体curl: (7) Failed to connect克隆 brew 本体仓库github.com/Homebrew/brewHomebrew 的程序本体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.shHomebrew 4.x 的 JSON APIError: 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_REMOTEbrew 本体仓库地址HOMEBREW_CORE_GIT_REMOTEhomebrew-core 仓库地址主要是老版本 Homebrew 需要HOMEBREW_API_DOMAINHomebrew 4.x 的 JSON API 下载域名HOMEBREW_BOTTLE_DOMAIN预编译二进制包的下载域名HOMEBREW_PIP_INDEX_URLPython 包的索引地址类似国内 pip 源把这几个变量指向国内镜像站再用官方安装脚本执行安装脚本会严格尊重这些变量全程不走 GitHub。这种方式比“先装完再换源”更省事因为你不需要在安装完之后再去改仓库地址。1.3 选哪个镜像源三个主流镜像的对比我用过的镜像里比较稳定的是清华 TUNA、阿里云和中科大。三者同步速度、更新频率都在可接受范围内决定选哪个主要看你所在的网络环境和习惯镜像站brew 仓库地址API / bottle 地址特点清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrewmirrors.tuna.tsinghua.edu.cn/homebrew-bottles更新较快文档齐全支持安装脚本镜像阿里云mirrors.aliyun.com/homebrewmirrors.aliyun.com/homebrew-bottles国内机房线路好云厂商维护容量大中科大mirrors.ustc.edu.cn/brew.gitmirrors.ustc.edu.cn/homebrew-bottles老牌高校源稳定性好我强烈建议不要同时混用多个源的地址比如 brew 仓库用清华、bottle 域名用中科大。镜像站的同步频率不一样某些版本包可能在 A 站有、B 站还没跟上混用容易出现 “No bottle available” 这种奇怪的问题。选定一个源全部走一个。2. 安装前的准备这五分钟能帮你避开大部分坑2.1 确认 macOS 版本与处理器架构镜像安装法的核心步骤对所有 macOS 版本基本一致但不同处理器的安装路径完全不同最好一开始就确认清楚。Intel Mac 的 Homebrew 默认装在/usr/localApple SiliconM 系列芯片的 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_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://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那说明环境变量没当前终端会话中导入或权限不对趁早 CtrlC 再排查。第二看到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_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_NO_AUTO_UPDATE1 EOF source ~/.zshrcHOMEBREW_NO_AUTO_UPDATE1是我个人强烈建议加的它表示每次安装软件时不让 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 repositorygit 仓库拉取失败确认 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 并 sourceYour 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 用到顺手了。