Homebrew国内安装脚本：Mac安装失败原因与镜像源配置指南

简介这份资源是面向 macOS 国内用户的 Homebrew 安装优化方案针对官方源下载缓慢、甚至无法连接的问题通过切换国内镜像源来提升安装与更新命令行工具的效率。包内共 12 个文件以 5 个 sh 脚本为主涵盖安装、卸载、Git 环境准备等环节另有 3 个 md 说明文档、2 张运行过程截图以及 LICENSE 等辅助文件压缩包约 458KB体积轻便、结构清晰。已有 1206 人学习下载说明该方案在中文开发者社区中具备一定认可度。读者可借助脚本自动完成镜像源配置与 Homebrew 部署省去手动修改配置文件的繁琐配套截图与说明文档便于对照执行、排查安装异常卸载脚本也方便环境清理。对于需要快速搭建 macOS 开发环境、又受限于网络条件的用户这份资源提供了可直接复用的工具与排错参考。1. Homebrew 国内安装脚本为什么你的 mac 装不上以及一条能跑通的路国内用 Mac 做开发的人几乎都绕不开 Homebrew。但真正卡住大多数人的不是 brew 本身而是第一次安装——curl卡在raw.githubusercontent.com、git clone到一半断流、装完brew install又卡在下载 bottle。你搜「mac安装homebrew失败」出来的方案十有八九让你换源但换完源brew update又报错。这篇不讲 Homebrew 是什么直接讲国内网络环境下怎么把安装脚本跑通、装完怎么让install不卡、以及卸载时那些残留目录到底在哪。适合两类人第一次在 Mac 上配环境的和装过但被源切换搞乱、想彻底重来的。核心思路只有一条安装脚本本身要能拿到装完之后 Git 远程和 bottle 下载源要一起换缺一个都会在后续某一步翻车。2. 安装脚本到底在做什么先看清它拉了什么再决定怎么换2.1 官方脚本的三段式结构Homebrew 的安装脚本本质是一个 bash 脚本执行流程分三段。第一段检测系统环境确认是 macOS 还是 Linux、有没有 Xcode Command Line Tools、当前 shell 是 zsh 还是 bash。第二段用git clone把brew仓库拉到/opt/homebrewApple Silicon或/usr/local/HomebrewIntel这一步是国内失败率最高的环节因为默认走github.com。第三段执行brew update --force和brew cleanup把仓库初始化好并清理缓存。很多人以为换个HOMEBREW_BREW_GIT_REMOTE就完事了其实脚本里 clone 的地址是硬编码在下载下来的 install.sh 里的。你直接curl官方脚本脚本内容本身是从raw.githubusercontent.com拿的这一步就可能超时。所以国内安装的核心不是「换源」而是「先拿到脚本再让脚本里的 clone 走国内镜像」。2.2 两种主流落地路径的取舍目前国内能跑通的方案就两类。一类是用中科大或清华的镜像把 install.sh 下载地址和脚本内的BREW_REPO、CORE_REPO都替换掉另一类是用 Gitee 上的镜像仓库把git clone的源整体换掉。前者更贴近官方流程后续brew update行为一致后者首次安装快但 Gitee 镜像同步有延迟brew update时可能拉不到最新 formula。我一般推荐中科大方案原因是它的镜像更新频率高且同时提供 brew.git、homebrew-core.git、homebrew-cask.git 三个仓库的镜像装完之后brew install下载 bottle 也能走镜像。清华源同样可用但历史上出现过 cask 镜像不同步的情况。选哪个不影响后续步骤关键是三个仓库要一起换只换 brew.git 不换 corebrew install照样卡。2.3 用中科大镜像跑通安装的最小命令下面这段是 Apple Silicon 机器上的完整流程Intel 机器把/opt/homebrew换成/usr/local即可。先设置环境变量再下载脚本最后执行。# 设置安装时的 Git 远程为中科大镜像 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 # 从中科大镜像下载 install.sh避免 raw.githubusercontent.com 超时 curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh -o install.sh # 执行安装脚本会读取上面三个环境变量 /bin/bash install.sh逻辑说明HOMEBREW_BREW_GIT_REMOTE控制 brew 仓库的 clone 地址HOMEBREW_CORE_GIT_REMOTE控制 core 仓库HOMEBREW_BOTTLE_DOMAIN控制预编译包下载地址。三个变量在安装脚本执行期间生效脚本内部会优先读取它们而不是默认的 GitHub 地址。curl那一步换成中科大提供的 install.sh 镜像解决脚本本身下载失败的问题。参数说明-fsSL中-f表示 HTTP 错误时不输出内容-s静默模式-S出错时显示错误-L跟随重定向。-o install.sh把脚本存到当前目录方便检查内容后再执行。如果你不放心直接跑可以先cat install.sh看一眼 clone 地址是否被正确替换。2.4 装完必须做的源固化安装脚本执行完只是当次生效新开终端后环境变量就没了。必须把镜像配置写进 shell 配置文件否则下一次brew update又走 GitHub。# 判断当前 shellzsh 写 ~/.zshrcbash 写 ~/.bash_profile echo export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git ~/.zshrc echo export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git ~/.zshrc echo export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles ~/.zshrc source ~/.zshrc # 验证当前生效的远程地址 git -C $(brew --repo) remote -v逻辑说明前三行把变量追加到~/.zshrcsource让当前终端立即生效。最后一行用brew --repo拿到 brew 仓库路径再用git remote -v确认远程地址已经是中科大而不是 GitHub。如果显示的还是github.com说明变量没生效或者安装时就没替换成功需要手动git remote set-url origin改。参数说明brew --repo返回的是 brew 仓库根目录Apple Silicon 下是/opt/homebrew/Homebrew。git -C指定仓库路径执行命令避免 cd 来 cd 去。这一步是后续所有brew install能不能走镜像的前提别跳过。3. 装完之后brew install 还是慢问题出在哪3.1 bottle 下载和 formula 更新的区别brew install慢有两种表现。一种是卡在Updating Homebrew...这是brew update在拉 formula 索引走的是 core 仓库的 Git 远程。另一种是卡在Downloading https://ghcr.io/...这是下载 bottle 预编译包走的是HOMEBREW_BOTTLE_DOMAIN。两者走的通道不同要分别处理。如果你只换了 brew.git 没换 core.gitbrew update会卡在拉 core 索引。如果你换了 Git 远程但没设HOMEBREW_BOTTLE_DOMAINbrew install会卡在 ghcr.io。很多人只做了前一步然后抱怨「换了源还是慢」就是漏了 bottle 这一环。3.2 验证三个通道是否都走镜像装完一个新包用brew install wget做验证观察输出里的下载地址。# 安装一个轻量包观察下载地址 brew install wget # 如果输出里出现 ghcr.io 或 github.com说明 bottle 源没生效 # 检查当前 bottle 源 echo $HOMEBREW_BOTTLE_DOMAIN # 检查 core 仓库远程 git -C $(brew --repo homebrew/core) remote -v逻辑说明brew install wget的输出会显示每个下载步骤的 URL。如果 bottle 下载地址是mirrors.ustc.edu.cn/homebrew-bottles说明配置正确。如果还是ghcr.io检查HOMEBREW_BOTTLE_DOMAIN是否在当前终端生效。brew --repo homebrew/core返回 core 仓库路径用git remote -v确认它的远程地址。参数说明brew --repo homebrew/core在 Apple Silicon 下返回/opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-core。这个路径下的 Git 远程如果还是 GitHubbrew update就会慢。可以用git -C $(brew --repo homebrew/core) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git手动改。3.3 已经装乱了怎么重置如果你之前换过多个源现在brew update报各种错最干净的做法是卸载重装。Homebrew 官方提供了卸载脚本但国内下载同样可能失败可以直接用本地命令删。# 官方卸载脚本如果网络能拿到 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh) # 如果上面拿不到手动删除Apple Silicon 路径 sudo rm -rf /opt/homebrew sudo rm -rf /usr/local/Homebrew sudo rm -rf /usr/local/Caskroom sudo rm -rf /usr/local/var/homebrew # 清理 shell 配置里的 brew 相关行 # 编辑 ~/.zshrc删掉 eval $(/opt/homebrew/bin/brew shellenv) 和镜像变量逻辑说明官方卸载脚本会检测安装路径并删除但脚本本身在 GitHub 上国内可能拿不到。手动删除时注意 Intel 和 Apple Silicon 路径不同/opt/homebrew是 Apple Silicon 的默认前缀/usr/local/Homebrew是 Intel 的。/usr/local/Caskroom和/usr/local/var/homebrew是 cask 和缓存目录不删干净重装可能出玄学问题。参数说明sudo rm -rf删除目录执行前确认路径拼写正确rm -rf没有后悔药。删完 shell 配置后新开终端brew命令应该找不到说明清理干净。重装时按第 2 章的流程走一遍三个环境变量在安装前就设好。4. 避坑与排查国内装 Homebrew 最常见的 5 个翻车现场4.1 现象curl 下载 install.sh 直接超时原因raw.githubusercontent.com在国内大部分网络下不可达curl默认没有超时限制时会一直挂起。解决不要用官方curl地址换成中科大或清华的 install.sh 镜像。如果镜像也拿不到用git clone方式从 Gitee 镜像拉脚本但注意 Gitee 镜像的脚本内容可能滞后。4.2 现象安装脚本执行到 git clone 卡住不动原因脚本内部 clone 的地址是 GitHub即使你设了HOMEBREW_BREW_GIT_REMOTE如果变量没 export 或者脚本版本不读取该变量仍然走默认地址。解决执行前确认export了三个变量并且用echo $HOMEBREW_BREW_GIT_REMOTE验证。如果脚本不读变量手动下载脚本后sed替换里面的BREW_REPO和CORE_REPO再执行。4.3 现象装完 brew 能用但 brew install 任何包都卡在 Updating原因brew update在拉 core 仓库索引core 的 Git 远程还是 GitHub。解决检查git -C $(brew --repo homebrew/core) remote -v如果是 GitHub用git remote set-url origin改成中科大镜像。改完执行brew update --verbose观察是否走镜像。4.4 现象brew install 下载 bottle 时提示 403 或 404原因HOMEBREW_BOTTLE_DOMAIN设的镜像地址不对或者镜像上没有对应 macOS 版本的 bottle。中科大镜像的 bottle 路径需要带/homebrew-bottles少写一段会 404。解决确认变量值是https://mirrors.ustc.edu.cn/homebrew-bottles末尾不要加斜杠。如果某个包确实没有镜像 bottle可以临时HOMEBREW_NO_BOTTLE_DOMAIN1 brew install --build-from-source从源码编译但耗时长。4.5 现象重装后 brew 命令找不到或者报 command not found原因shell 配置里的eval $(brew shellenv)路径不对或者重装后路径变了Intel 换 Apple Silicon 迁移时常见。解决确认brew实际安装路径Apple Silicon 是/opt/homebrew/bin/brewIntel 是/usr/local/bin/brew。在~/.zshrc里写对应路径的eval然后source ~/.zshrc。如果两个路径都有残留先清理再配。5. 进阶用 Brewfile 和镜像锁定做可复现的环境迁移装好 Homebrew 只是起点真正省事的是把「装了哪些包」变成可复现的配置。brew bundle配合Brewfile能把所有 formula 和 cask 声明式管理换机器时一条命令恢复。但国内环境下brew bundle同样走 Git 和 bottle 通道所以镜像配置要先固化好。先导出当前环境的 Brewfile# 导出所有已安装的 formula 和 cask 到 Brewfile brew bundle dump --file~/Brewfile --force # 查看内容确认 tap、brew、cask 三类都包含 cat ~/Brewfile逻辑说明brew bundle dump会扫描当前安装的所有包生成一个包含tap、brew、cask、mas四类条目的文件。--force覆盖已有文件。这个文件可以提交到 Git 仓库换机器时brew bundle install --file~/Brewfile就能批量恢复。参数说明--file指定输出路径默认是当前目录的Brewfile。--force不加的话如果文件已存在会报错。mas条目对应 App Store 应用恢复时需要先登录 App Store国内网络下mas可能超时可以暂时注释掉。恢复时的关键是把镜像变量在brew bundle install之前就 export 好否则批量安装会逐个卡在 GitHub。我一般把镜像变量写进~/.zshrc后再执行恢复。另外brew bundle不管理 shell 配置和系统级设置这些还是要手动迁移。一个容易忽略的点是Brewfile里的 tap 条目。如果你之前 tap 过第三方仓库恢复时brew tap会走 GitHub。可以在Brewfile里把不常用的 tap 删掉只保留核心的homebrew/core和homebrew/cask减少恢复时的网络依赖。最后说个我自己的习惯每次换机器或重装系统先按第 2 章把 Homebrew 装好、镜像固化再brew bundle install。顺序反了的话brew bundle会在没配镜像的情况下跑然后你就得看着几十个包一个个超时。这个顺序我踩过两次现在写进 checklist 里。希望帮到你。本文还有配套的精品资源点击获取