1. 安装为什么总是失败先搞清楚卡在哪个环节这两年但凡有人让我远程看Homebrew问题十个里至少有八个卡在同一幕终端刷了一长串报错红字写着curl: (7) Failed to connect to raw.githubusercontent.com port 443。剩下两个一个卡在git clone https://github.com/Homebrew/brew半天没动静另一个盯着下载进度条看了五分钟纹丝不动。今天这篇就围绕“Homebrew国内镜像自动安装”这条主线从原理到实际命令把 Intel Mac 和 Apple Silicon Mac 上常见的安装失败、安装慢、装完没法 update 的坑一次讲透。不管你是刚接触 macOS 开发环境的新人还是被 Homebrew 折磨过的老用户这套用镜像源完成自动安装的方案都值得直接抄作业。1.1 一条安装命令牵出的三个网络节点先看官方安装命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)。很多人只看到“一条命令”但这条命令背后其实要经过三个独立的网络环节下载install.sh脚本本身它在raw.githubusercontent.com上脚本执行后从github.com/Homebrew/brew拉取 Homebrew 主体仓库后续安装软件时还要从ghcr.io或formulae.brew.sh拉取预编译包和公式元数据。这三个节点只要有一个连接不稳定整条链路就断了。raw.githubusercontent.com在国内的连接状况尤其不稳定这就是大量安装失败报错的直接来源。很多人以为是自己命令敲错了其实是网络路径绕了一大圈卡在了入口处。还有个容易被忽略的点DNS 解析。有时候 GitHub 域名本身能 ping 通但到你本地的解析结果被污染或异常curl 会卡在 TLS 握手阶段表现就是长时间转圈或者SSL_ERROR_SYSCALL。遇到这种情况先换公共 DNS 再测一下很多时候问题就解决了。1.2 新版 Homebrew 的架构变化老教程为什么失效Homebrew 4.0 之后有一个非常关键的变化默认不再拉取整个homebrew-core的 git 仓库而是通过 API 接口获取公式元数据。这意味着老教程里那些“替换 homebrew-core.git 地址”的操作在新版本里已经不能完全解决 update 慢的问题了。新版最需要关心的是HOMEBREW_API_DOMAIN这个环境变量。它决定brew update和brew search时去哪个地址拉取公式信息。如果你配置了国内镜像的 API 地址update 速度会有质的提升。这也是为什么很多人配置了HOMEBREW_BREW_GIT_REMOTE之后update 还是慢——因为新版根本没走 git 仓库更新公式而是走 API。同时要注意 Intel Mac 和 Apple Silicon 的差异。Intel 默认安装路径是/usr/local/HomebrewApple Silicon 是/opt/homebrew。不同的路径设计会影响权限、PATH 配置和后续脚本执行方式。特别是 Intel Mac 上/usr/local目录权限如果被改乱过安装过程会莫名卡住这在后面实操部分我会详细说。2. 自动安装的核心思路用“换源脚本镜像”一次性解决很多人的第一反应是反复重试官方命令或者手动下载安装包再拷贝过去。这些办法不是不行但都很被动。官方安装脚本逻辑本身是干净的问题只在下载源。所以最优解是让脚本从国内镜像站下载脚本内部涉及 GitHub 的地址也一并替换掉。这就是镜像安装脚本的原理。2.1 官方脚本到底做了什么镜像脚本怎么改的官方install.sh做的事情概括起来就三步检查系统环境macOS 版本、命令行工具、架构、克隆 Homebrew 主体仓库、初始化目录和权限。镜像脚本改动的地方很克制主要就是把脚本开头用于下载硬编码的 GitHub 地址替换成国内镜像站对应的地址。以中科大镜像站提供的install.sh为例它把https://github.com/Homebrew/brew替换为https://mirrors.ustc.edu.cn/brew.git把homebrew-core也指向了科大的homebrew-core.git。这样脚本一旦跑起来整个安装过程就完全不依赖 GitHub不需要再手动修改任何东西。这种思路比“先装官方版再改源”要稳得多。因为如果官方版装到一半失败系统里可能已经留下半截 Homebrew 目录后续修复比一开始用镜像脚本直接装更麻烦。安装类工具最怕的就是“进行到一半”的状态。2.2 三大镜像源怎么选中科大、清华、阿里国内常用的 macOS 软件镜像源主要有中科大、清华和阿里云三家。我实际用下来的感受是中科大和清华的 Homebrew 覆盖最完整既有 git 仓库镜像也有 bottles 预编译包镜像和 API 镜像阿里云主要提供 bottles 镜像适合只解决安装慢的场景但 git 仓库和 API 方面覆盖不如前两家全。镜像源brew 本体仓库homebrew-coreAPI 元数据bottles 预编译包中科大支持支持支持支持清华支持支持支持支持阿里云不支持不支持不支持支持建议你直接选一家作为主力不要交叉混用。混用多个源容易出“元数据来自 A安装包来自 B”的错位问题排查起来很麻烦。我个人主力用中科大因为它的目录结构和文档更新比较及时脚本镜像也齐全。2.3NONINTERACTIVE参数真正无人值守的关键官方安装脚本支持一个环境变量NONINTERACTIVE1。设置后脚本不会停下来让你按回车确认、也不会问你是否安装命令行工具全程自动执行。这个参数对自动化部署、远程脚本执行、或者不想盯着终端等人的人来说非常关键。配合镜像脚本使用时命令就变成一行NONINTERACTIVE1 /bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew/install.sh)执行后你可以喝杯水回来看结果。脚本会打印安装日志看到Installation successful或类似字样就说明成了。这里要注意即使加了NONINTERACTIVE如果后期需要写入/usr/localIntel Mac 场景且目录权限不足脚本还是有可能中途失败所以安装前检查目录权限是必要的。3. 手把手实操一条命令完成镜像自动安装3.1 安装前检查架构、目录权限、命令行工具在跑安装命令之前花两分钟确认三件事能省掉后面大量的排查时间。第一确认芯片架构。在终端执行uname -m输出arm64就是 Apple Silicon输出x86_64就是 Intel 或在 Rosetta 环境下。确认架构的目的是判断后续 Homebrew 会装到哪个目录以及 PATH 该怎么配。第二确认命令行工具。执行xcode-select -p如果输出/Library/Developer/CommandLineTools或/Applications/Xcode.app/...说明就绪。如果提示error: unable to locate xcode-select先执行xcode-select --install把 Command Line Tools 装上再继续。第三检查目录状态。对于 Intel Mac/usr/local如果存在且权限不对建议先执行sudo chown -R $(whoami) /usr/local注意这条命令在全新机器上可以直接跑但如果机器上已经装了其他软件执行前先看一眼/usr/local里有没有你不认识的东西。Apple Silicon 场景下/opt/homebrew通常不存在不需要提前处理。3.2 中科大镜像脚本安装Intel 与 Apple Silicon 通用确认完环境直接把这一行复制进终端NONINTERACTIVE1 /bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew/install.sh)脚本会自动检测架构、选择正确的安装路径、完成 Homebrew 主体仓库的克隆。如果之前没装 Command Line Tools脚本会尝试自动安装这个过程需要联网从苹果开发者中心下载资源耗时看你网络情况。安装完成后验证一下brew --version which brew如果提示command not found说明 Homebrew 虽然装进了目录但还没进入当前 shell 的 PATH。解决办法是手动加载环境# Apple Silicon eval $(/opt/homebrew/bin/brew shellenv) # Intel eval $(/usr/local/bin/brew shellenv)执行完which brew应该能看到对应路径。为了让新开的终端窗口也生效需要把对应语句追加到 shell 配置文件里。3.3 清华备选方案与安装后自检如果你那边访问中科大有延迟或者想用清华镜像操作也简单。清华提供的是安装脚本仓库先克隆再执行git clone --depth1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git cd install NONINTERACTIVE1 /bin/bash install.sh这里用--depth1只是拉取安装脚本仓库的最新版本不需要完整历史记录能省不少时间。清华的脚本同样会把后续的 brew 仓库、core 仓库地址改到清华镜像上。安装完成后的自检我推荐多看一个信息brew config这个命令会打印出 Homebrew 的完整配置包括 macOS 版本、CLT 路径、以及各个HOMEBREW_*环境变量。你一眼就能看出来当前走的是哪个源。如果某些域名为空说明还没配置下一步就要处理环境变量的问题。4. 安装只是开始把 brew 的日常流量也切到国内镜像脚本安装解决了“装得上”的问题但如果你装完就万事大吉后面brew update和brew install还是会因为默认源是 GitHub 而频繁超时。安装只是第一步日常使用也得让 Homebrew 继续走国内镜像。4.1 配置环境变量让 update 和 install 都走镜像打开你的 shell 配置文件。macOS 默认 shell 是 zsh所以通常是~/.zshrc老用户如果切过 bash就写~/.bash_profile。在文件末尾加入以下内容以中科大为示例export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git保存后执行source ~/.zshrc让配置生效。用清华的同学把地址换成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_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这四个变量的分工很明确HOMEBREW_API_DOMAIN管公式元数据HOMEBREW_BOTTLE_DOMAIN管预编译二进制包HOMEBREW_BREW_GIT_REMOTE管 Homebrew 本体更新HOMEBREW_CORE_GIT_REMOTE管 core 仓库主要用于旧版本或强制 git 模式的场景。把它们都配上相当于把 Homebrew 的每一条网络请求都指向了国内。4.2 理解HOMEBREW_API_DOMAIN新版 Homebrew 的关键变量很多旧教程只教配HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE但在 Homebrew 4.x 下这两个变量主要负责 brew 本体的升级和那些不使用 API 模式的操作。真正影响日常体验的是HOMEBREW_API_DOMAIN。默认情况下Homebrew 的 API 请求会发往formulae.brew.sh。这个域名在国内访问速度时好时坏尤其在brew update要拉取大量公式变更信息时慢起来能让你怀疑机器死机了。把HOMEBREW_API_DOMAIN指到镜像站之后公式信息、版本变更、依赖关系都能快速同步。如果你发现某个包brew info能看但brew install却报formula not found大概率就是 API 元数据和本地缓存不同步。执行一次brew update再试通常能解决前提是你已经配置好 API 镜像源。4.3 实际效果验证与 Cask 镜像补充配置完环境变量跑一个实际安装看效果。我建议拿wget或zlib做测试因为它们都有预编译包且依赖链相对简单。brew update brew install zlib正常情况下的输出应该是下载链接直接指向mirrors.ustc.edu.cn或你配置的镜像地址下载速度稳定不会卡在Downloading ...长时间不动。如果下载地址还是ghcr.io或homebrew.bintray.com说明环境变量没生效回到 4.1 检查配置。还有一个场景是安装图形化软件比如 Chrome、VS Code这时候走的是 Homebrew Cask。Cask 的下载源通常指向软件官方地址镜像源影响有限。但 Cask 仓库本身的更新走的是 git所以HOMEBREW_CORE_GIT_REMOTE和 API 域名配置好之后brew update会顺畅很多brew install --cask的体验也跟着变好。5. 高频报错排查与避坑实录即便用了镜像源不同机器上的历史问题千奇百怪。我自己踩过、也帮人排查过不少下面把遇到频率最高的几类整理出来方便你对症处理。5.1 常见报错速查表报错信息直接原因处理方式curl: (7) Failed to connect to raw.githubusercontent.com port 443官方脚本下载链路不通改用中科大或清华镜像脚本安装fatal: unable to access https://github.com/Homebrew/brew/brew 仓库 clone 不过去先设置HOMEBREW_BREW_GIT_REMOTE再执行安装脚本Error: homebrew-core is a shallow clonecore 仓库是浅克隆无法正常更新进入对应的 homebrew-core 目录执行git fetch --unshallowCannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)终端以 x86_64 模式运行在 Apple Silicon 上退出当前终端重新打开纯 arm64 终端或执行arch -arm64 /bin/zshAnother active Homebrew update process is already in progress上一次 update 中断留下了锁删除$(brew --prefix)/var/homebrew/locks下的锁文件后重试curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALLTLS 握手失败网络链路不稳定检查 DNS 设置或切换镜像源重新执行排查时有一个顺序很重要先确认配置再看网络最后才看命令。很多人的问题出在环境变量没写进~/.zshrc或者写进去了但没执行source导致配置看起来“有”实则没生效。5.2 卸载残留怎么清干净Homebrew 官方提供了卸载脚本但国内访问 GitHub 不稳时脚本未必能顺利下载。而且官方卸载脚本主要删除核心安装目录缓存、日志、Cask 安装的应用本体这些残留不会都清掉。如果你打算彻底重装下面这些路径手动过一遍更干净路径内容/usr/local/Homebrew或/opt/homebrewHomebrew 主目录/usr/local/Cellar或/opt/homebrew/Cellar通过 Homebrew 安装的软件本体/usr/local/Caskroom或/opt/homebrew/Caskroom通过 Cask 安装的图形化应用~/Library/Caches/Homebrew下载缓存日积月累可能占好几个 GB~/Library/Logs/Homebrew安装和更新日志~/.zshrc中追加的HOMEBREW_*环境变量若不再使用 Homebrew需手动删除如果你只是觉得 Homebrew 状态不正常想重装不一定非要卸载干净再装。多数情况下清了缓存、删掉 locks、修正环境变量后重试问题就解决了。只有当你确定要彻底告别 Homebrew 或者怀疑目录结构损坏时才需要走完整的卸载清理流程。5.3 几条容易忽略的实操小技巧先说 PATH 的问题。brew命令找不到绝大多数情况不是安装失败而是 PATH 没配好。Apple Silicon 机器要确认/opt/homebrew/bin在 PATH 中Intel 机器要确认/usr/local/bin在 PATH 中。用echo $PATH检查时看到对应路径存在且排在前面就对了。再说权限问题。Intel Mac 上/usr/local目录是历史遗留的“公共目录”很多软件都会往里写东西。Homebrew 安装时如果遇到Permission denied不要直接sudo chmod -R 777 /usr/local图省事这会破坏整个目录的权限模型后面会有更诡异的问题。建议只针对需要写入的子目录做属主调整比如/usr/local/Homebrew、/usr/local/Cellar、/usr/local/bin等。最后提一下缓存。Homebrew 的下载缓存会越来越大尤其当你频繁安装和卸载大型软件时。定期清一下缓存对保持系统清爽很有帮助brew cleanup这条命令会删除旧版本的残留包和无用缓存。如果你想让缓存清得更彻底可以手动删~/Library/Caches/Homebrew下的内容但注意这样做会让后续重装某个软件时重新下载。我在实际使用中比较建议保留缓存只定期brew cleanup在速度与空间之间取一个平衡。还有一个容易被忽略的点Homebrew 在安装需要编译的软件时如果本地缺少编译依赖日志里会刷出一堆configure: error: ...之类的报错让人误以为是网络问题。这种情况先确认brew doctor输出是否干净再看具体缺的是哪个依赖针对性brew install对应的依赖即可。说到底Homebrew 本身是一个非常成熟的工具90% 的安装问题都出在下载链路上。把源码换成国内镜像把环境变量写对把 PATH 配好剩下的就只是时间问题。我在实际使用中体会最深的一点是镜像源别贪多选一个信得过的长期保持配置稳定远比频繁切换源更省心。
Homebrew国内镜像自动安装全攻略：从原理到实操解决安装失败与更新慢
1. 安装为什么总是失败先搞清楚卡在哪个环节这两年但凡有人让我远程看Homebrew问题十个里至少有八个卡在同一幕终端刷了一长串报错红字写着curl: (7) Failed to connect to raw.githubusercontent.com port 443。剩下两个一个卡在git clone https://github.com/Homebrew/brew半天没动静另一个盯着下载进度条看了五分钟纹丝不动。今天这篇就围绕“Homebrew国内镜像自动安装”这条主线从原理到实际命令把 Intel Mac 和 Apple Silicon Mac 上常见的安装失败、安装慢、装完没法 update 的坑一次讲透。不管你是刚接触 macOS 开发环境的新人还是被 Homebrew 折磨过的老用户这套用镜像源完成自动安装的方案都值得直接抄作业。1.1 一条安装命令牵出的三个网络节点先看官方安装命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)。很多人只看到“一条命令”但这条命令背后其实要经过三个独立的网络环节下载install.sh脚本本身它在raw.githubusercontent.com上脚本执行后从github.com/Homebrew/brew拉取 Homebrew 主体仓库后续安装软件时还要从ghcr.io或formulae.brew.sh拉取预编译包和公式元数据。这三个节点只要有一个连接不稳定整条链路就断了。raw.githubusercontent.com在国内的连接状况尤其不稳定这就是大量安装失败报错的直接来源。很多人以为是自己命令敲错了其实是网络路径绕了一大圈卡在了入口处。还有个容易被忽略的点DNS 解析。有时候 GitHub 域名本身能 ping 通但到你本地的解析结果被污染或异常curl 会卡在 TLS 握手阶段表现就是长时间转圈或者SSL_ERROR_SYSCALL。遇到这种情况先换公共 DNS 再测一下很多时候问题就解决了。1.2 新版 Homebrew 的架构变化老教程为什么失效Homebrew 4.0 之后有一个非常关键的变化默认不再拉取整个homebrew-core的 git 仓库而是通过 API 接口获取公式元数据。这意味着老教程里那些“替换 homebrew-core.git 地址”的操作在新版本里已经不能完全解决 update 慢的问题了。新版最需要关心的是HOMEBREW_API_DOMAIN这个环境变量。它决定brew update和brew search时去哪个地址拉取公式信息。如果你配置了国内镜像的 API 地址update 速度会有质的提升。这也是为什么很多人配置了HOMEBREW_BREW_GIT_REMOTE之后update 还是慢——因为新版根本没走 git 仓库更新公式而是走 API。同时要注意 Intel Mac 和 Apple Silicon 的差异。Intel 默认安装路径是/usr/local/HomebrewApple Silicon 是/opt/homebrew。不同的路径设计会影响权限、PATH 配置和后续脚本执行方式。特别是 Intel Mac 上/usr/local目录权限如果被改乱过安装过程会莫名卡住这在后面实操部分我会详细说。2. 自动安装的核心思路用“换源脚本镜像”一次性解决很多人的第一反应是反复重试官方命令或者手动下载安装包再拷贝过去。这些办法不是不行但都很被动。官方安装脚本逻辑本身是干净的问题只在下载源。所以最优解是让脚本从国内镜像站下载脚本内部涉及 GitHub 的地址也一并替换掉。这就是镜像安装脚本的原理。2.1 官方脚本到底做了什么镜像脚本怎么改的官方install.sh做的事情概括起来就三步检查系统环境macOS 版本、命令行工具、架构、克隆 Homebrew 主体仓库、初始化目录和权限。镜像脚本改动的地方很克制主要就是把脚本开头用于下载硬编码的 GitHub 地址替换成国内镜像站对应的地址。以中科大镜像站提供的install.sh为例它把https://github.com/Homebrew/brew替换为https://mirrors.ustc.edu.cn/brew.git把homebrew-core也指向了科大的homebrew-core.git。这样脚本一旦跑起来整个安装过程就完全不依赖 GitHub不需要再手动修改任何东西。这种思路比“先装官方版再改源”要稳得多。因为如果官方版装到一半失败系统里可能已经留下半截 Homebrew 目录后续修复比一开始用镜像脚本直接装更麻烦。安装类工具最怕的就是“进行到一半”的状态。2.2 三大镜像源怎么选中科大、清华、阿里国内常用的 macOS 软件镜像源主要有中科大、清华和阿里云三家。我实际用下来的感受是中科大和清华的 Homebrew 覆盖最完整既有 git 仓库镜像也有 bottles 预编译包镜像和 API 镜像阿里云主要提供 bottles 镜像适合只解决安装慢的场景但 git 仓库和 API 方面覆盖不如前两家全。镜像源brew 本体仓库homebrew-coreAPI 元数据bottles 预编译包中科大支持支持支持支持清华支持支持支持支持阿里云不支持不支持不支持支持建议你直接选一家作为主力不要交叉混用。混用多个源容易出“元数据来自 A安装包来自 B”的错位问题排查起来很麻烦。我个人主力用中科大因为它的目录结构和文档更新比较及时脚本镜像也齐全。2.3NONINTERACTIVE参数真正无人值守的关键官方安装脚本支持一个环境变量NONINTERACTIVE1。设置后脚本不会停下来让你按回车确认、也不会问你是否安装命令行工具全程自动执行。这个参数对自动化部署、远程脚本执行、或者不想盯着终端等人的人来说非常关键。配合镜像脚本使用时命令就变成一行NONINTERACTIVE1 /bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew/install.sh)执行后你可以喝杯水回来看结果。脚本会打印安装日志看到Installation successful或类似字样就说明成了。这里要注意即使加了NONINTERACTIVE如果后期需要写入/usr/localIntel Mac 场景且目录权限不足脚本还是有可能中途失败所以安装前检查目录权限是必要的。3. 手把手实操一条命令完成镜像自动安装3.1 安装前检查架构、目录权限、命令行工具在跑安装命令之前花两分钟确认三件事能省掉后面大量的排查时间。第一确认芯片架构。在终端执行uname -m输出arm64就是 Apple Silicon输出x86_64就是 Intel 或在 Rosetta 环境下。确认架构的目的是判断后续 Homebrew 会装到哪个目录以及 PATH 该怎么配。第二确认命令行工具。执行xcode-select -p如果输出/Library/Developer/CommandLineTools或/Applications/Xcode.app/...说明就绪。如果提示error: unable to locate xcode-select先执行xcode-select --install把 Command Line Tools 装上再继续。第三检查目录状态。对于 Intel Mac/usr/local如果存在且权限不对建议先执行sudo chown -R $(whoami) /usr/local注意这条命令在全新机器上可以直接跑但如果机器上已经装了其他软件执行前先看一眼/usr/local里有没有你不认识的东西。Apple Silicon 场景下/opt/homebrew通常不存在不需要提前处理。3.2 中科大镜像脚本安装Intel 与 Apple Silicon 通用确认完环境直接把这一行复制进终端NONINTERACTIVE1 /bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew/install.sh)脚本会自动检测架构、选择正确的安装路径、完成 Homebrew 主体仓库的克隆。如果之前没装 Command Line Tools脚本会尝试自动安装这个过程需要联网从苹果开发者中心下载资源耗时看你网络情况。安装完成后验证一下brew --version which brew如果提示command not found说明 Homebrew 虽然装进了目录但还没进入当前 shell 的 PATH。解决办法是手动加载环境# Apple Silicon eval $(/opt/homebrew/bin/brew shellenv) # Intel eval $(/usr/local/bin/brew shellenv)执行完which brew应该能看到对应路径。为了让新开的终端窗口也生效需要把对应语句追加到 shell 配置文件里。3.3 清华备选方案与安装后自检如果你那边访问中科大有延迟或者想用清华镜像操作也简单。清华提供的是安装脚本仓库先克隆再执行git clone --depth1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git cd install NONINTERACTIVE1 /bin/bash install.sh这里用--depth1只是拉取安装脚本仓库的最新版本不需要完整历史记录能省不少时间。清华的脚本同样会把后续的 brew 仓库、core 仓库地址改到清华镜像上。安装完成后的自检我推荐多看一个信息brew config这个命令会打印出 Homebrew 的完整配置包括 macOS 版本、CLT 路径、以及各个HOMEBREW_*环境变量。你一眼就能看出来当前走的是哪个源。如果某些域名为空说明还没配置下一步就要处理环境变量的问题。4. 安装只是开始把 brew 的日常流量也切到国内镜像脚本安装解决了“装得上”的问题但如果你装完就万事大吉后面brew update和brew install还是会因为默认源是 GitHub 而频繁超时。安装只是第一步日常使用也得让 Homebrew 继续走国内镜像。4.1 配置环境变量让 update 和 install 都走镜像打开你的 shell 配置文件。macOS 默认 shell 是 zsh所以通常是~/.zshrc老用户如果切过 bash就写~/.bash_profile。在文件末尾加入以下内容以中科大为示例export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git保存后执行source ~/.zshrc让配置生效。用清华的同学把地址换成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_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这四个变量的分工很明确HOMEBREW_API_DOMAIN管公式元数据HOMEBREW_BOTTLE_DOMAIN管预编译二进制包HOMEBREW_BREW_GIT_REMOTE管 Homebrew 本体更新HOMEBREW_CORE_GIT_REMOTE管 core 仓库主要用于旧版本或强制 git 模式的场景。把它们都配上相当于把 Homebrew 的每一条网络请求都指向了国内。4.2 理解HOMEBREW_API_DOMAIN新版 Homebrew 的关键变量很多旧教程只教配HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE但在 Homebrew 4.x 下这两个变量主要负责 brew 本体的升级和那些不使用 API 模式的操作。真正影响日常体验的是HOMEBREW_API_DOMAIN。默认情况下Homebrew 的 API 请求会发往formulae.brew.sh。这个域名在国内访问速度时好时坏尤其在brew update要拉取大量公式变更信息时慢起来能让你怀疑机器死机了。把HOMEBREW_API_DOMAIN指到镜像站之后公式信息、版本变更、依赖关系都能快速同步。如果你发现某个包brew info能看但brew install却报formula not found大概率就是 API 元数据和本地缓存不同步。执行一次brew update再试通常能解决前提是你已经配置好 API 镜像源。4.3 实际效果验证与 Cask 镜像补充配置完环境变量跑一个实际安装看效果。我建议拿wget或zlib做测试因为它们都有预编译包且依赖链相对简单。brew update brew install zlib正常情况下的输出应该是下载链接直接指向mirrors.ustc.edu.cn或你配置的镜像地址下载速度稳定不会卡在Downloading ...长时间不动。如果下载地址还是ghcr.io或homebrew.bintray.com说明环境变量没生效回到 4.1 检查配置。还有一个场景是安装图形化软件比如 Chrome、VS Code这时候走的是 Homebrew Cask。Cask 的下载源通常指向软件官方地址镜像源影响有限。但 Cask 仓库本身的更新走的是 git所以HOMEBREW_CORE_GIT_REMOTE和 API 域名配置好之后brew update会顺畅很多brew install --cask的体验也跟着变好。5. 高频报错排查与避坑实录即便用了镜像源不同机器上的历史问题千奇百怪。我自己踩过、也帮人排查过不少下面把遇到频率最高的几类整理出来方便你对症处理。5.1 常见报错速查表报错信息直接原因处理方式curl: (7) Failed to connect to raw.githubusercontent.com port 443官方脚本下载链路不通改用中科大或清华镜像脚本安装fatal: unable to access https://github.com/Homebrew/brew/brew 仓库 clone 不过去先设置HOMEBREW_BREW_GIT_REMOTE再执行安装脚本Error: homebrew-core is a shallow clonecore 仓库是浅克隆无法正常更新进入对应的 homebrew-core 目录执行git fetch --unshallowCannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)终端以 x86_64 模式运行在 Apple Silicon 上退出当前终端重新打开纯 arm64 终端或执行arch -arm64 /bin/zshAnother active Homebrew update process is already in progress上一次 update 中断留下了锁删除$(brew --prefix)/var/homebrew/locks下的锁文件后重试curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALLTLS 握手失败网络链路不稳定检查 DNS 设置或切换镜像源重新执行排查时有一个顺序很重要先确认配置再看网络最后才看命令。很多人的问题出在环境变量没写进~/.zshrc或者写进去了但没执行source导致配置看起来“有”实则没生效。5.2 卸载残留怎么清干净Homebrew 官方提供了卸载脚本但国内访问 GitHub 不稳时脚本未必能顺利下载。而且官方卸载脚本主要删除核心安装目录缓存、日志、Cask 安装的应用本体这些残留不会都清掉。如果你打算彻底重装下面这些路径手动过一遍更干净路径内容/usr/local/Homebrew或/opt/homebrewHomebrew 主目录/usr/local/Cellar或/opt/homebrew/Cellar通过 Homebrew 安装的软件本体/usr/local/Caskroom或/opt/homebrew/Caskroom通过 Cask 安装的图形化应用~/Library/Caches/Homebrew下载缓存日积月累可能占好几个 GB~/Library/Logs/Homebrew安装和更新日志~/.zshrc中追加的HOMEBREW_*环境变量若不再使用 Homebrew需手动删除如果你只是觉得 Homebrew 状态不正常想重装不一定非要卸载干净再装。多数情况下清了缓存、删掉 locks、修正环境变量后重试问题就解决了。只有当你确定要彻底告别 Homebrew 或者怀疑目录结构损坏时才需要走完整的卸载清理流程。5.3 几条容易忽略的实操小技巧先说 PATH 的问题。brew命令找不到绝大多数情况不是安装失败而是 PATH 没配好。Apple Silicon 机器要确认/opt/homebrew/bin在 PATH 中Intel 机器要确认/usr/local/bin在 PATH 中。用echo $PATH检查时看到对应路径存在且排在前面就对了。再说权限问题。Intel Mac 上/usr/local目录是历史遗留的“公共目录”很多软件都会往里写东西。Homebrew 安装时如果遇到Permission denied不要直接sudo chmod -R 777 /usr/local图省事这会破坏整个目录的权限模型后面会有更诡异的问题。建议只针对需要写入的子目录做属主调整比如/usr/local/Homebrew、/usr/local/Cellar、/usr/local/bin等。最后提一下缓存。Homebrew 的下载缓存会越来越大尤其当你频繁安装和卸载大型软件时。定期清一下缓存对保持系统清爽很有帮助brew cleanup这条命令会删除旧版本的残留包和无用缓存。如果你想让缓存清得更彻底可以手动删~/Library/Caches/Homebrew下的内容但注意这样做会让后续重装某个软件时重新下载。我在实际使用中比较建议保留缓存只定期brew cleanup在速度与空间之间取一个平衡。还有一个容易被忽略的点Homebrew 在安装需要编译的软件时如果本地缺少编译依赖日志里会刷出一堆configure: error: ...之类的报错让人误以为是网络问题。这种情况先确认brew doctor输出是否干净再看具体缺的是哪个依赖针对性brew install对应的依赖即可。说到底Homebrew 本身是一个非常成熟的工具90% 的安装问题都出在下载链路上。把源码换成国内镜像把环境变量写对把 PATH 配好剩下的就只是时间问题。我在实际使用中体会最深的一点是镜像源别贪多选一个信得过的长期保持配置稳定远比频繁切换源更省心。