在 macOS 上折腾开发环境你迟早会跟 Homebrew也就是大家常说的 brew打交道。但很多人第一次用 brew都卡在同一个地方安装慢、下载慢、更新慢跑个brew install能把人急出白头发。尤其是热搜词里那些 “mac 安装 brew”“Intel 安装 brew” 的高频搜索本质上都是同一个需求怎么让 brew 在国内的网络环境下也能顺利跑起来。这篇不谈理论直接把我折腾过、验证过的加速方案整理出来从安装到换源、从配置到排错照着抄就行。先说清楚一个事实brew 本身并不慢慢的是它默认去访问的服务器。Homebrew 的代码仓库在 GitHub预编译软件包bottle放在 ghcr.ioAPI 数据也在 GitHub 上。这些服务在国内网络环境下经常连不上或者极其缓慢于是就有了“brew 安装慢”这个经典问题。解决方案也很明确把 brew 的下载地址切换到国内可直连的镜像源。下面从原理到实操一步步来。1. 为什么 brew 安装会慢到让人抓狂1.1 慢在哪一步先搞清楚瓶颈很多人遇到 brew 慢第一反应是“换个源”但换了之后依然卡。原因很简单没找到真正的瓶颈。brew 慢通常发生在三个环节对应三个完全不同的网络请求地址安装脚本本身官方安装脚本install.sh存放在raw.githubusercontent.com上这个域名在国内访问经常超时卡住的第一站就是它。仓库数据Homebrew 及其核心仓库homebrew-core、homebrew-cask存放在 GitHubgit clone和git fetch都需要访问 GitHub。软件预编译包bottle安装软件时下载的二进制压缩包存放在ghcr.ioGitHub Container Registry。这个域名在国内的连通性更差经常是下载到一半就断掉。所以一个完整的加速方案要覆盖这三个环节安装脚本换源或手动安装、仓库地址换源、bottle 下载地址换源。只处理其中一个另一个问题很快就会冒出来。1.2 芯片不同安装路径完全不同在动手之前必须先确认你的 Mac 是 Intel 还是 Apple Silicon因为 brew 的安装路径和后续操作路径完全不同。这个区分也对应了热搜词里的 “Intel 安装 brew” 和 “M 芯片安装 brew”。Apple SiliconM1、M2、M3、M4 等的 brew 默认安装在/opt/homebrew命令路径是/opt/homebrew/bin/brew。Intel Mac 的 brew 默认安装在/usr/local软链接在/usr/local/bin/brew。如果你照着网上的教程复制粘贴最典型的翻车事故就是把/opt/homebrew的命令原封不动用在 Intel 机器上结果bash: /opt/homebrew/bin/brew: No such file or directory。查看芯片型号最简单的方法是在终端执行uname -m输出arm64就是 Apple Silicon输出x86_64就是 Intel。记住这个结果后面所有命令都要据此区分。2. 安装 brew 阶段如何加速2.1 安装前的必备检查安装 brew 之前有几个前置条件需要确认否则安装过程会中途失败。首先macOS 必须已经安装了 Command Line Tools命令行工具。brew 依赖 Git、curl 等基础工具。如果没装执行brew --version会提示你先安装比较省事的方式是执行xcode-select --install系统会弹出图形化安装界面耐心等它装完即可。如果这个命令报错说软件源不可用也可以直接从 Apple 开发者官网下载对应版本的 Command Line Tools 安装包手动安装。其次确认你的 Git 版本不要太老。可以在终端里看git --version如果 Git 版本过低brew 装完后可能会报一些奇怪的错误升级 Git 也很让人头疼。好在多数新 macOS 自带版本都够用。2.2 使用国内镜像安装脚本一次到位官网推荐的安装命令是/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这条命令在国内环境经常连raw.githubusercontent.com都访问不了更不用说后面的仓库拉取了。我建议直接用国内镜像脚本。以中科大镜像为例它的安装脚本会自动设置好环境变量再调用官方安装流程。Intel 和 Apple Silicon 都能用/bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)这个脚本执行后会自动把 brew 相关的远程仓库地址指向中科大镜像整个过程显著提速。实测下来原来可能卡死 10 分钟以上的安装脚本换成镜像后一般在 1 到 2 分钟内就能完成。阿里云镜像也提供了类似的安装引导路径是/bin/bash -c $(curl -fsSL https://mirrors.aliyun.com/homebrew/install.sh)清华大学的镜像则推荐你先设置环境变量再执行官方脚本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_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)之所以推荐中科大镜像脚本是因为它把环境变量设置都封装进去了对新手最友好。但要注意脚本执行完后会提示你把环境变量写到 shell 配置文件里这一步千万别跳过。2.3 手动 git clone 安装备选方案如果自动安装脚本因为各种奇怪原因失败还有一个备选方案手动从镜像仓库 clone 整个 brew 仓库。Apple Silicon 机器执行sudo mkdir -p /opt/homebrew sudo chown -R $USER:admin /opt/homebrew git clone --depth1 https://mirrors.ustc.edu.cn/brew.git /opt/homebrewIntel 机器执行sudo mkdir -p /usr/local/Homebrew sudo chown -R $USER:admin /usr/local/Homebrew git clone --depth1 https://mirrors.ustc.edu.cn/brew.git /usr/local/Homebrew然后手动创建命令入口。Apple Silicon 执行sudo ln -s /opt/homebrew/bin/brew /usr/local/bin/brew其实 Apple Silicon 机器不需要把 brew 软链到/usr/local/bin因为/opt/homebrew/bin加进 PATH 就可以直接用了。在~/.zshrc里加入export PATH/opt/homebrew/bin:$PATHIntel 机器如果git clone出来的目录里有bin/brew可以用软链接方式把命令暴露出来sudo ln -s /usr/local/Homebrew/bin/brew /usr/local/bin/brew手动 clone 的坏处是没有安装脚本里那些辅助逻辑后续 core、cask 仓库都要自己配置所以只建议作为自动脚本失败时的兜底方案。3. 安装完成后的换源加速3.1 4.0 新机制API 源比 core 源更关键Homebrew 在 4.0 版本之后做了个重要改动默认不再通过git clone整个homebrew-core仓库来获取软件信息而是通过 JSON API 按需拉取。这意味着HOMEBREW_CORE_GIT_REMOTE的作用在变小真正影响速度的是HOMEBREW_API_DOMAIN。很多老教程还在让你只配 core 仓库配完发现 brew install 依然慢就是因为 API 拉取的地址还是官方的https://formulae.brew.sh/api。虽然这个地址相对稳定但在国内也有明显延迟。正确的做法是把 API 域名一起换成镜像源。所以下面给出的环境变量里HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN是最关键的两个HOMEBREW_BREW_GIT_REMOTE负责 brew 自身的更新也不可或缺。3.2 环境变量换源法中科大/清华/阿里/腾讯最推荐、也最干净的做法是直接设置 shell 环境变量。把下面任一方案追加到你的 shell 配置文件。macOS Catalina 之后默认 shell 是 zsh配置文件是~/.zshrc如果你还在用 bash就写进~/.bash_profile。中科大源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api清华源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_CASK_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api阿里云源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-core.git export HOMEBREW_CASK_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles/api腾讯云源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/homebrew-core.git export HOMEBREW_CASK_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.cloud.tencent.com/homebrew/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.cloud.tencent.com/homebrew/homebrew-bottles/api设置完执行source ~/.zshrc让配置立即生效。然后跑一句brew update --force强制让 brew 从新源重新拉取数据。执行过程里注意观察输出看看仓库地址是否已经变成镜像域名。3.3 顺手优化的两个环境变量除了换源还有两个环境变量值得顺手加上能大幅改善日常使用体验。第一个是HOMEBREW_NO_AUTO_UPDATE1。brew 在每次执行安装命令前都会尝试自动更新自己这个行为在国内网络下经常导致命令卡住好几分钟。关闭自动更新后brew install的响应速度会明显提升需要更新时手动执行brew update即可。第二个是HOMEBREW_NO_INSTALL_CLEANUP1。旧版本 brew 每次安装完会做清理新版本默认策略已经变了但如果你的版本还在自动清理也可以显式关掉。顺手加这两个变量export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1此外HOMEBREW_NO_ANALYTICS1可以关闭匿名统计上报既省一点流量也减少一次网络请求export HOMEBREW_NO_ANALYTICS1都写完后的~/.zshrc大概是这个样子export PATH/opt/homebrew/bin:$PATH export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1 export HOMEBREW_NO_ANALYTICS14. 安装软件时的其他提速技巧4.1 bottle 下载加速换源后brew install下载的软件包走的是HOMEBREW_BOTTLE_DOMAIN指向的镜像。这一步是安装软件时的最大流量来源也最容易出问题。可以验证一下某个软件的下载地址是否已经变成镜像brew info wget输出信息里会标明From: https://mirrors.ustc.edu.cn/homebrew-bottles/...之类的地址说明 bottle 源生效了。如果显示的还是ghcr.io开头的地址说明环境变量没生效检查~/.zshrc是否加载、新终端是否重开。4.2 强制用预编译包避免源码编译brew 理论上偏爱预编译的 bottle但在某些情况下会尝试从源码编译。比如你指定了--build-from-source或者该软件没有提供适配你系统的 bottle。源码编译的时间往往非常长动辄十几分钟对网络要求其实不高但对耐心要求极高。正常情况下如果本地已经有 bottle可以直接强制使用brew install --force-bottle wget这条命令会强制使用预编译包不进行源码编译。如果你的机器是 Intel Mac而某个软件官方已经停止提供 Intel 版 bottle那无论网速多快都只能源码编译这种情况只能等或者换一个功能相近的软件。4.3 用 brew -v 定位卡点告别白等很多人遇到brew install卡住就急得跺脚其实可以先看它到底卡在哪一步。常用调试方式是brew install -v wget-v参数会输出详细的下载日志包括正在请求的 URL、当前下载进度。如果卡在下载 URL 上说明源有问题如果卡在处理依赖上可能是依赖没装好如果卡在编译上说明在编译源码。看清卡点再对症下药比盲目重试高效得多。5. 实操记录从零到装完 wget 的全过程5.1 现场实录拿一台空的 Intel Mac 举例完整跑一遍加速流程。终端先看架构uname -m输出x86_64。安装命令行工具xcode-select --install弹窗后确认安装等它完成。然后执行中科大安装脚本/bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)脚本跑完会在终端末尾提示添加环境变量。按提示把下面内容写入~/.zshrcexport PATH/usr/local/bin:$PATH export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_NO_AUTO_UPDATE1注意 Intel 机器上 Homebrew 会提示你加/usr/local/bin到 PATH。执行source ~/.zshrc然后看一眼版本brew --version能正常输出版本号说明核心安装成功。接着装一个最常用的 wgetbrew install wget全程盯着输出下载阶段可以看到从mirrors.ustc.edu.cn拉取 bottle 的信息。整个安装过程在一两分钟内结束对比之前动不动就卡死的体验差异非常明显。Apple Silicon 机器上的流程几乎一样只是脚本执行完后 PATH 要写/opt/homebrew/bin仓库目录也是/opt/homebrew其余命令相同。5.2 如何验证源已经生效安装完之后可以用几个命令确认所有源确实都切到了镜像brew doctor brew configbrew config的输出里会列出当前生效的各种地址变量。重点看这几行HOMEBREW_BREW_GIT_REMOTE应该指向镜像仓库。HOMEBREW_BOTTLE_DOMAIN应该指向镜像的 bottles 地址。HOMEBREW_API_DOMAIN应该指向镜像的 API 地址。如果哪一项显示为官方 GitHub 地址说明对应的环境变量没写对或没重新加载配置回到~/.zshrc检查。brew doctor如果输出Your system is ready to brew恭喜你brew 已经处于健康可用的状态。6. 典型问题排查与避坑指南6.1 常见错误对照表我把实际踩过、以及在群里看到别人踩过的高频问题整理成一张表方便快速对照症状可能原因处理方法安装脚本提示curl: (7) Failed to connect to raw.githubusercontent.com安装脚本源被卡住改用中科大brew-install.sh脚本brew install卡在Updating Homebrew...自动更新导致HOMEBREW_NO_AUTO_UPDATE1或手动brew update下载软件时进度条长时间不动bottle 源还是官方地址检查HOMEBREW_BOTTLE_DOMAIN是否生效Error: No such file or directory rb_sysopen安装路径不对重新确认芯片架构路径写成/opt/homebrew还是/usr/localPermission denied或cannot overwrite directory目录权限不对用sudo chown -R $USER:admin修复 Homebrew 目录权限command not found: brewPATH 没配置好把对应路径写入~/.zshrc并source6.2 换源后想还原官方源怎么办不想一直用镜像源或者某个镜像临时抽风想切回官方不用重装 brew。只要把~/.zshrc里的相关环境变量删掉再恢复仓库的远端地址就行。先解除环境变量干扰重新打开终端会自动失效或者手动执行unset HOMEBREW_BREW_GIT_REMOTE unset HOMEBREW_CORE_GIT_REMOTE unset HOMEBREW_BOTTLE_DOMAIN unset HOMEBREW_API_DOMAIN然后进入 brew 安装目录把 git remote 改回 GitHubcd $(brew --prefix) git remote set-url origin https://github.com/Homebrew/brew.git最后执行brew update重新拉取。完整切换回官方源的过程网上也有很多一键脚本可以偷懒但不建议直接跑不明来源的脚本手动改清楚自己心里有数。6.3 几个我踩过的坑第一个坑是修改了/usr/local的全局权限。早期教程喜欢让人sudo chown -R $(whoami) /usr/local把整个目录都改成当前用户所有。这样短期内确实解决了权限报错但会让 macOS 的系统目录权限变得一团糟后续升级系统或运行其他软件都可能出问题。正确做法是只对 Homebrew 自己的目录做权限修改/usr/local里的其他东西别乱动。第二个坑是忽略了 API 域名。很多人看教程只设置了 brew 和 core 两个仓库地址装那些不需要源码编译的软件还好可一旦某个软件需要走 API 拉取信息就会明显变慢。我自己有段时间brew search一直卡顿后来才发现是 API 域名没换。4.0 之后的版本里HOMEBREW_API_DOMAIN的价值甚至超过 core 仓库。第三个坑是把自动更新完全关掉之后长时间不更新。HOMEBREW_NO_AUTO_UPDATE1确实让日常安装快了很多但 brew 的软件定义是持续更新的几个月不更新后各种依赖关系会变得很陈旧再执行brew update时反而会因为跨度太大拉取大量数据。建议至少每个月手动执行一次brew update让容器保持新鲜。第四个坑是忽略 cask 仓库的配置。如果你经常用brew install --cask安装图形化软件比如浏览器、编辑器这类那么HOMEBREW_CASK_GIT_REMOTE也很重要。虽然新版 API 模式让 cask 信息也走接口但某些老版本或特定场景下还是会直接拉取 cask 仓库提前配置好能少踩一个坑。最后一个建议用完某个镜像源发现速度不理想就换一个。中科大、清华、阿里云这几个源在不同时间段、不同网络环境下的表现会有差异没有绝对的最优解。切换源的成本很低改几行环境变量再执行brew update --force就行多试几个找到你自己网络环境下最稳的那个。我个人的习惯是中科大做主力、清华做备用一条命令就能切换。另外如果你身边有朋友装了老版本 brew建议顺手提醒他执行一次brew update升级到新版本。旧版本和新版本在源配置上差异不小老教程里的一些方法在新版本里未必适用避免大家一起踩坑。
macOS Homebrew安装慢？国内镜像源加速方案全攻略（覆盖Intel与M芯片）
在 macOS 上折腾开发环境你迟早会跟 Homebrew也就是大家常说的 brew打交道。但很多人第一次用 brew都卡在同一个地方安装慢、下载慢、更新慢跑个brew install能把人急出白头发。尤其是热搜词里那些 “mac 安装 brew”“Intel 安装 brew” 的高频搜索本质上都是同一个需求怎么让 brew 在国内的网络环境下也能顺利跑起来。这篇不谈理论直接把我折腾过、验证过的加速方案整理出来从安装到换源、从配置到排错照着抄就行。先说清楚一个事实brew 本身并不慢慢的是它默认去访问的服务器。Homebrew 的代码仓库在 GitHub预编译软件包bottle放在 ghcr.ioAPI 数据也在 GitHub 上。这些服务在国内网络环境下经常连不上或者极其缓慢于是就有了“brew 安装慢”这个经典问题。解决方案也很明确把 brew 的下载地址切换到国内可直连的镜像源。下面从原理到实操一步步来。1. 为什么 brew 安装会慢到让人抓狂1.1 慢在哪一步先搞清楚瓶颈很多人遇到 brew 慢第一反应是“换个源”但换了之后依然卡。原因很简单没找到真正的瓶颈。brew 慢通常发生在三个环节对应三个完全不同的网络请求地址安装脚本本身官方安装脚本install.sh存放在raw.githubusercontent.com上这个域名在国内访问经常超时卡住的第一站就是它。仓库数据Homebrew 及其核心仓库homebrew-core、homebrew-cask存放在 GitHubgit clone和git fetch都需要访问 GitHub。软件预编译包bottle安装软件时下载的二进制压缩包存放在ghcr.ioGitHub Container Registry。这个域名在国内的连通性更差经常是下载到一半就断掉。所以一个完整的加速方案要覆盖这三个环节安装脚本换源或手动安装、仓库地址换源、bottle 下载地址换源。只处理其中一个另一个问题很快就会冒出来。1.2 芯片不同安装路径完全不同在动手之前必须先确认你的 Mac 是 Intel 还是 Apple Silicon因为 brew 的安装路径和后续操作路径完全不同。这个区分也对应了热搜词里的 “Intel 安装 brew” 和 “M 芯片安装 brew”。Apple SiliconM1、M2、M3、M4 等的 brew 默认安装在/opt/homebrew命令路径是/opt/homebrew/bin/brew。Intel Mac 的 brew 默认安装在/usr/local软链接在/usr/local/bin/brew。如果你照着网上的教程复制粘贴最典型的翻车事故就是把/opt/homebrew的命令原封不动用在 Intel 机器上结果bash: /opt/homebrew/bin/brew: No such file or directory。查看芯片型号最简单的方法是在终端执行uname -m输出arm64就是 Apple Silicon输出x86_64就是 Intel。记住这个结果后面所有命令都要据此区分。2. 安装 brew 阶段如何加速2.1 安装前的必备检查安装 brew 之前有几个前置条件需要确认否则安装过程会中途失败。首先macOS 必须已经安装了 Command Line Tools命令行工具。brew 依赖 Git、curl 等基础工具。如果没装执行brew --version会提示你先安装比较省事的方式是执行xcode-select --install系统会弹出图形化安装界面耐心等它装完即可。如果这个命令报错说软件源不可用也可以直接从 Apple 开发者官网下载对应版本的 Command Line Tools 安装包手动安装。其次确认你的 Git 版本不要太老。可以在终端里看git --version如果 Git 版本过低brew 装完后可能会报一些奇怪的错误升级 Git 也很让人头疼。好在多数新 macOS 自带版本都够用。2.2 使用国内镜像安装脚本一次到位官网推荐的安装命令是/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这条命令在国内环境经常连raw.githubusercontent.com都访问不了更不用说后面的仓库拉取了。我建议直接用国内镜像脚本。以中科大镜像为例它的安装脚本会自动设置好环境变量再调用官方安装流程。Intel 和 Apple Silicon 都能用/bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)这个脚本执行后会自动把 brew 相关的远程仓库地址指向中科大镜像整个过程显著提速。实测下来原来可能卡死 10 分钟以上的安装脚本换成镜像后一般在 1 到 2 分钟内就能完成。阿里云镜像也提供了类似的安装引导路径是/bin/bash -c $(curl -fsSL https://mirrors.aliyun.com/homebrew/install.sh)清华大学的镜像则推荐你先设置环境变量再执行官方脚本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_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)之所以推荐中科大镜像脚本是因为它把环境变量设置都封装进去了对新手最友好。但要注意脚本执行完后会提示你把环境变量写到 shell 配置文件里这一步千万别跳过。2.3 手动 git clone 安装备选方案如果自动安装脚本因为各种奇怪原因失败还有一个备选方案手动从镜像仓库 clone 整个 brew 仓库。Apple Silicon 机器执行sudo mkdir -p /opt/homebrew sudo chown -R $USER:admin /opt/homebrew git clone --depth1 https://mirrors.ustc.edu.cn/brew.git /opt/homebrewIntel 机器执行sudo mkdir -p /usr/local/Homebrew sudo chown -R $USER:admin /usr/local/Homebrew git clone --depth1 https://mirrors.ustc.edu.cn/brew.git /usr/local/Homebrew然后手动创建命令入口。Apple Silicon 执行sudo ln -s /opt/homebrew/bin/brew /usr/local/bin/brew其实 Apple Silicon 机器不需要把 brew 软链到/usr/local/bin因为/opt/homebrew/bin加进 PATH 就可以直接用了。在~/.zshrc里加入export PATH/opt/homebrew/bin:$PATHIntel 机器如果git clone出来的目录里有bin/brew可以用软链接方式把命令暴露出来sudo ln -s /usr/local/Homebrew/bin/brew /usr/local/bin/brew手动 clone 的坏处是没有安装脚本里那些辅助逻辑后续 core、cask 仓库都要自己配置所以只建议作为自动脚本失败时的兜底方案。3. 安装完成后的换源加速3.1 4.0 新机制API 源比 core 源更关键Homebrew 在 4.0 版本之后做了个重要改动默认不再通过git clone整个homebrew-core仓库来获取软件信息而是通过 JSON API 按需拉取。这意味着HOMEBREW_CORE_GIT_REMOTE的作用在变小真正影响速度的是HOMEBREW_API_DOMAIN。很多老教程还在让你只配 core 仓库配完发现 brew install 依然慢就是因为 API 拉取的地址还是官方的https://formulae.brew.sh/api。虽然这个地址相对稳定但在国内也有明显延迟。正确的做法是把 API 域名一起换成镜像源。所以下面给出的环境变量里HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN是最关键的两个HOMEBREW_BREW_GIT_REMOTE负责 brew 自身的更新也不可或缺。3.2 环境变量换源法中科大/清华/阿里/腾讯最推荐、也最干净的做法是直接设置 shell 环境变量。把下面任一方案追加到你的 shell 配置文件。macOS Catalina 之后默认 shell 是 zsh配置文件是~/.zshrc如果你还在用 bash就写进~/.bash_profile。中科大源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api清华源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_CASK_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api阿里云源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-core.git export HOMEBREW_CASK_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles/api腾讯云源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/homebrew-core.git export HOMEBREW_CASK_GIT_REMOTEhttps://mirrors.cloud.tencent.com/homebrew/homebrew-cask.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.cloud.tencent.com/homebrew/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.cloud.tencent.com/homebrew/homebrew-bottles/api设置完执行source ~/.zshrc让配置立即生效。然后跑一句brew update --force强制让 brew 从新源重新拉取数据。执行过程里注意观察输出看看仓库地址是否已经变成镜像域名。3.3 顺手优化的两个环境变量除了换源还有两个环境变量值得顺手加上能大幅改善日常使用体验。第一个是HOMEBREW_NO_AUTO_UPDATE1。brew 在每次执行安装命令前都会尝试自动更新自己这个行为在国内网络下经常导致命令卡住好几分钟。关闭自动更新后brew install的响应速度会明显提升需要更新时手动执行brew update即可。第二个是HOMEBREW_NO_INSTALL_CLEANUP1。旧版本 brew 每次安装完会做清理新版本默认策略已经变了但如果你的版本还在自动清理也可以显式关掉。顺手加这两个变量export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1此外HOMEBREW_NO_ANALYTICS1可以关闭匿名统计上报既省一点流量也减少一次网络请求export HOMEBREW_NO_ANALYTICS1都写完后的~/.zshrc大概是这个样子export PATH/opt/homebrew/bin:$PATH export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1 export HOMEBREW_NO_ANALYTICS14. 安装软件时的其他提速技巧4.1 bottle 下载加速换源后brew install下载的软件包走的是HOMEBREW_BOTTLE_DOMAIN指向的镜像。这一步是安装软件时的最大流量来源也最容易出问题。可以验证一下某个软件的下载地址是否已经变成镜像brew info wget输出信息里会标明From: https://mirrors.ustc.edu.cn/homebrew-bottles/...之类的地址说明 bottle 源生效了。如果显示的还是ghcr.io开头的地址说明环境变量没生效检查~/.zshrc是否加载、新终端是否重开。4.2 强制用预编译包避免源码编译brew 理论上偏爱预编译的 bottle但在某些情况下会尝试从源码编译。比如你指定了--build-from-source或者该软件没有提供适配你系统的 bottle。源码编译的时间往往非常长动辄十几分钟对网络要求其实不高但对耐心要求极高。正常情况下如果本地已经有 bottle可以直接强制使用brew install --force-bottle wget这条命令会强制使用预编译包不进行源码编译。如果你的机器是 Intel Mac而某个软件官方已经停止提供 Intel 版 bottle那无论网速多快都只能源码编译这种情况只能等或者换一个功能相近的软件。4.3 用 brew -v 定位卡点告别白等很多人遇到brew install卡住就急得跺脚其实可以先看它到底卡在哪一步。常用调试方式是brew install -v wget-v参数会输出详细的下载日志包括正在请求的 URL、当前下载进度。如果卡在下载 URL 上说明源有问题如果卡在处理依赖上可能是依赖没装好如果卡在编译上说明在编译源码。看清卡点再对症下药比盲目重试高效得多。5. 实操记录从零到装完 wget 的全过程5.1 现场实录拿一台空的 Intel Mac 举例完整跑一遍加速流程。终端先看架构uname -m输出x86_64。安装命令行工具xcode-select --install弹窗后确认安装等它完成。然后执行中科大安装脚本/bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)脚本跑完会在终端末尾提示添加环境变量。按提示把下面内容写入~/.zshrcexport PATH/usr/local/bin:$PATH export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_NO_AUTO_UPDATE1注意 Intel 机器上 Homebrew 会提示你加/usr/local/bin到 PATH。执行source ~/.zshrc然后看一眼版本brew --version能正常输出版本号说明核心安装成功。接着装一个最常用的 wgetbrew install wget全程盯着输出下载阶段可以看到从mirrors.ustc.edu.cn拉取 bottle 的信息。整个安装过程在一两分钟内结束对比之前动不动就卡死的体验差异非常明显。Apple Silicon 机器上的流程几乎一样只是脚本执行完后 PATH 要写/opt/homebrew/bin仓库目录也是/opt/homebrew其余命令相同。5.2 如何验证源已经生效安装完之后可以用几个命令确认所有源确实都切到了镜像brew doctor brew configbrew config的输出里会列出当前生效的各种地址变量。重点看这几行HOMEBREW_BREW_GIT_REMOTE应该指向镜像仓库。HOMEBREW_BOTTLE_DOMAIN应该指向镜像的 bottles 地址。HOMEBREW_API_DOMAIN应该指向镜像的 API 地址。如果哪一项显示为官方 GitHub 地址说明对应的环境变量没写对或没重新加载配置回到~/.zshrc检查。brew doctor如果输出Your system is ready to brew恭喜你brew 已经处于健康可用的状态。6. 典型问题排查与避坑指南6.1 常见错误对照表我把实际踩过、以及在群里看到别人踩过的高频问题整理成一张表方便快速对照症状可能原因处理方法安装脚本提示curl: (7) Failed to connect to raw.githubusercontent.com安装脚本源被卡住改用中科大brew-install.sh脚本brew install卡在Updating Homebrew...自动更新导致HOMEBREW_NO_AUTO_UPDATE1或手动brew update下载软件时进度条长时间不动bottle 源还是官方地址检查HOMEBREW_BOTTLE_DOMAIN是否生效Error: No such file or directory rb_sysopen安装路径不对重新确认芯片架构路径写成/opt/homebrew还是/usr/localPermission denied或cannot overwrite directory目录权限不对用sudo chown -R $USER:admin修复 Homebrew 目录权限command not found: brewPATH 没配置好把对应路径写入~/.zshrc并source6.2 换源后想还原官方源怎么办不想一直用镜像源或者某个镜像临时抽风想切回官方不用重装 brew。只要把~/.zshrc里的相关环境变量删掉再恢复仓库的远端地址就行。先解除环境变量干扰重新打开终端会自动失效或者手动执行unset HOMEBREW_BREW_GIT_REMOTE unset HOMEBREW_CORE_GIT_REMOTE unset HOMEBREW_BOTTLE_DOMAIN unset HOMEBREW_API_DOMAIN然后进入 brew 安装目录把 git remote 改回 GitHubcd $(brew --prefix) git remote set-url origin https://github.com/Homebrew/brew.git最后执行brew update重新拉取。完整切换回官方源的过程网上也有很多一键脚本可以偷懒但不建议直接跑不明来源的脚本手动改清楚自己心里有数。6.3 几个我踩过的坑第一个坑是修改了/usr/local的全局权限。早期教程喜欢让人sudo chown -R $(whoami) /usr/local把整个目录都改成当前用户所有。这样短期内确实解决了权限报错但会让 macOS 的系统目录权限变得一团糟后续升级系统或运行其他软件都可能出问题。正确做法是只对 Homebrew 自己的目录做权限修改/usr/local里的其他东西别乱动。第二个坑是忽略了 API 域名。很多人看教程只设置了 brew 和 core 两个仓库地址装那些不需要源码编译的软件还好可一旦某个软件需要走 API 拉取信息就会明显变慢。我自己有段时间brew search一直卡顿后来才发现是 API 域名没换。4.0 之后的版本里HOMEBREW_API_DOMAIN的价值甚至超过 core 仓库。第三个坑是把自动更新完全关掉之后长时间不更新。HOMEBREW_NO_AUTO_UPDATE1确实让日常安装快了很多但 brew 的软件定义是持续更新的几个月不更新后各种依赖关系会变得很陈旧再执行brew update时反而会因为跨度太大拉取大量数据。建议至少每个月手动执行一次brew update让容器保持新鲜。第四个坑是忽略 cask 仓库的配置。如果你经常用brew install --cask安装图形化软件比如浏览器、编辑器这类那么HOMEBREW_CASK_GIT_REMOTE也很重要。虽然新版 API 模式让 cask 信息也走接口但某些老版本或特定场景下还是会直接拉取 cask 仓库提前配置好能少踩一个坑。最后一个建议用完某个镜像源发现速度不理想就换一个。中科大、清华、阿里云这几个源在不同时间段、不同网络环境下的表现会有差异没有绝对的最优解。切换源的成本很低改几行环境变量再执行brew update --force就行多试几个找到你自己网络环境下最稳的那个。我个人的习惯是中科大做主力、清华做备用一条命令就能切换。另外如果你身边有朋友装了老版本 brew建议顺手提醒他执行一次brew update升级到新版本。旧版本和新版本在源配置上差异不小老教程里的一些方法在新版本里未必适用避免大家一起踩坑。
)
