Mac安装Homebrew报错128：homebrew-core克隆失败解决

mac 上第一次装 Homebrew，脚本跑到一半，终端里突然甩出来一行红字：Error: Failure while executing; git clone https://github.com/Homebrew/homebrew-core /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core --depth=1 exited with 128。这个场景我见过太多次了，尤其是换了新机器、或者隔了一两年重装系统的朋友，第一反应往往是"我是不是把 Mac 搞坏了"。其实没有，这条报错的本质非常简单：安装脚本在某一刻需要从远端把一个 Git 仓库拉到本地，而这个拉取动作失败了。它既可能是网络在长连接上断掉了，也可能是本地 Git 配置里有历史包袱，还可能是/usr/local这个目录的归属关系不对。这篇文章我把这条报错从链路、根因、配置、实操到排查完整拆一遍，包含可以直接抄的命令和参数解释。无论你是刚接触命令行的新手，还是装过好几台机器的老手，都能从里面找到对应自己那台机器的解法。

1. 先搞清楚这条报错卡在了哪一步

很多人拿到报错就去搜"homebrew 安装失败"，然后照着几年前的文章一通乱敲，结果把本来能用的环境搞得更乱。正确的顺序是先看懂安装脚本在干什么，知道自己卡在第几环，再决定动手方向。这一节把整条链路拆开讲。

1.1 Homebrew 安装脚本的执行顺序

Homebrew 的官方安装脚本并不是"下载一个二进制丢到某个目录"这么简单，它是一段会分阶段执行的 shell 逻辑。我把它大致归成四步：

1. 环境体检：检查系统版本、CPU 架构（Intel 还是 Apple Silicon）、有没有装 Xcode Command Line Tools。如果没装，脚本会尝试触发xcode-select --install，这时候会弹出一个系统对话框，很多人就是在这里点了"取消"或者没等它装完，后面直接崩。
2. 确定安装前缀：Intel 机型走/usr/local，Apple Silicon 机型走/opt/homebrew。这个前缀决定了后续所有路径，包括报错里出现的那个/usr/local/Homebrew/Library/Taps/...。
3. 克隆主仓库：把Homebrew/brew这个仓库拉到本地，也就是安装前缀下的Homebrew目录。这一步体量不大，一般能过。
4. 克隆或初始化 Tap：这就是出问题的高发区。老版本脚本会去克隆Homebrew/homebrew-core，这个仓库历史很长、体量很大，浅克隆也要拉不少数据；新版本（4.0 之后）默认改成走 API 模式，不再把homebrew-core完整克隆到本地，而是按需请求元数据。

看到这里你应该能对上号了：报错信息里出现homebrew-core，说明你的脚本走到了第 4 步，而且用的是"从 Git 源拉取"这种模式。这一步失败，前面三步其实都已经成功了，所以你的机器并没有被搞坏，只是最后一环没接上。

1.2 为什么偏偏是 homebrew-core 最容易失败

同样是 git clone，为什么克隆brew主仓库没事，克隆homebrew-core就挂了？原因有三个，都很实际：

• 数据量大：homebrew-core记录的是成千上万个软件包的 Formula 定义，历史提交极其密集。哪怕加了--depth=1，拉下来的对象也比主仓库大一个量级。传输时间越长，中途出现抖动、连接被重置的概率就越高。
• 对连接持续性要求高：Git 的智能传输协议在克隆过程中需要维持较长时间的会话。网络稍有波动，服务端或客户端任意一侧断掉，整个 clone 就前功尽弃，然后返回退出码 128。
• 失败没有断点续传：git clone不像下载器那样支持断点续传。断了就是从零开始，重试几次都在同一个位置失败，给人的感觉是"永远装不上"。

理解这三点之后，解决思路就清楚了：要么缩短传输距离和体积，要么降低对单次长连接的依赖，要么干脆绕开这一步不走 Git 源。

提示：新版 Homebrew 默认使用 API 模式，正常情况下安装时是不需要克隆homebrew-core的。如果你的脚本还在做这件事，说明要么脚本本身比较旧，要么环境变量里显式关掉了 API 模式。这一点在下一节展开。

1.3 退出码 128 说明了什么

很多人只看到"Failure while executing"就慌了，其实关键信息在后面那个数字。Git 的退出码 128 是一个通用致命错误码，常见触发场景包括：远端仓库不存在或路径写错、网络连接中断、TLS 证书校验失败、认证被拒绝、目标目录已存在且非空。

这里要特别区分一件事：Homebrew 的这些仓库都是公开仓库，匿名克隆本来就不需要任何凭据。如果你在报错里看到认证相关的字样，那基本不是仓库要求你登录，而是你本地的 Git 配置或者凭据管理器往里塞了什么不该塞的东西。热词里常出现的"需要带账号密码"那类说法，其实是对 GitHub 认证机制的误读——GitHub 早就不支持账号密码推送了，私有仓库要的是 Personal Access Token，而公开仓库根本不需要这一套。

2. 三类根因与快速定位方法

报错文案是同一条，但底层原因差别很大。我习惯把它分成网络层、Git 配置层、目录权限层三类。分类的价值在于：每一类的验证手段和修复动作完全不同，分清楚了就不会瞎折腾。

2.1 网络层：长连接中途断掉

这是占比最高的一类。表现特征是：手动curl一下仓库首页能通，浏览器也能打开对应的站点，但git clone跑到某个百分比就卡死或者报错。原因是短请求能过，不代表长连接能稳。

验证方法很直接，找一个体积相当的公开仓库试一下：

# 手动做一次浅克隆，把仓库扔到临时目录，不污染系统路径 git clone --depth=1 https://github.com/Homebrew/homebrew-core /tmp/test-core-clone # 只看连通性和响应头，不下载内容 curl -I -m 10 https://github.com # 看解析结果是否正常 nslookup github.com

如果/tmp/test-core-clone这次成功了，说明网络本身能走通，问题更可能是偶发的中断或者安装脚本执行时的超时阈值太紧。如果这次也失败，那就属于持续性问题，建议直接跳到第 3 节，用镜像源替换掉默认地址。

另外提醒一点：如果你所在的环境有企业级的出口策略、校园网的流量整形，长连接被中途掐断是很常见的。这类问题不是靠改参数能彻底解决的，换源是更务实的选择。

2.2 Git 配置层：历史遗留的网络参数

这一类最容易被忽略，也最容易让人抓狂。很多人在第一台机器上为了临时解决某个问题，往全局配置里写过一些网络转发类的参数，之后换了机器、换了网络环境，这些参数被同步过来了（比如通过 dotfiles 仓库），结果所有 Git 操作都被导向一个已经不存在的地址。

先看看全局配置里有什么：

# 列出所有全局配置项 git config --global --list # 顺手备份一份，改坏了能还原 git config --global --list > ~/gitconfig-backup.txt

重点检查两类内容：一类是http.或https.开头、值是一串地址的配置项；另一类是url.xxx.insteadOf这种改写规则。后者的作用是"把某个地址前缀自动替换成另一个"，如果以前为了换源写过，而目标源现在不可用，就会出现"明明输入的是 A 地址，实际访问的是 B 地址"的诡异现象。

清理方法：

# 逐条删除确认没用的配置，例如 git config --global --unset-all http.postBuffer git config --global --unset-all url.https://example.invalid/.insteadOf

删完再重新跑一次git config --global --list确认干净了。这一步做完，再回到安装流程，很多"莫名其妙"的失败就消失了。

2.3 权限层与磁盘层：被忽视的硬性条件

还有两类失败跟网络一点关系都没有，但因为报错文案一样，经常被误判。

权限问题：/usr/local这个目录在 macOS 上的归属比较特殊。如果你之前用过sudo手动在里面创建过目录，或者在老教程指导下执行过chown，可能导致安装脚本没有写权限。验证方式：

# 看目录归属和权限 ls -ld /usr/local ls -ld /usr/local/Homebrew 2>/dev/null # 看当前用户 whoami

如果/usr/local/Homebrew存在但归属不是你自己，安装脚本就会在创建或写入时失败。这里我要特别提醒：不要照抄网上"sudo chown -R $(whoami) /usr/local/*"这类命令。它会把系统级目录的归属一并改掉，短期内看起来问题解决了，后续会出现权限混乱、系统更新异常等一堆后遗症。正确做法是删掉 Homebrew 相关的残留目录，让安装脚本自己重建。

磁盘空间问题：homebrew-core完整克隆加上后续的缓存，占用比很多人想象的大。先确认剩余空间：

# 人类可读的方式看磁盘剩余 df -h / # 看 Homebrew 目录当前占了多少 du -sh /usr/local/Homebrew 2>/dev/null

剩余空间低于 10GB 的时候，我会建议先清理再装。空间不足导致的中断，往往表现为"跑到 80% 突然失败"，非常具有迷惑性。

3. 换掉 clone 目标：环境变量与镜像源配置

前面说过，最务实的解法是不要让安装脚本去访问默认的远端地址，而是把它指向一个就近的镜像源。Homebrew 官方是支持通过环境变量指定 Git 远端和 Bottle 下载地址的，这不是什么野路子，是写在文档里的机制。这一节把相关变量一个一个讲清楚。

3.1 关键环境变量逐个解释

国内几个主流的高校镜像站都提供 Homebrew 的镜像，常见的有中科大（USTC）和清华（TUNA）。它们给出的具体路径会随版本调整，所以我的建议是：执行前先去镜像站的页面上确认当前给出的地址，不要照抄网上几年前的命令。下面的示例只是结构演示，实际路径请以镜像站当期说明为准。

# 安装阶段临时生效，写进当前 shell 会话即可 export HOMEBREW_BREW_GIT_REMOTE="https://<镜像站>/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://<镜像站>/homebrew-core.git" export HOMEBREW_API_DOMAIN="https://<镜像站>/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://<镜像站>/homebrew-bottles"

这里有个细节值得说：这几个变量写在当前会话里，只对当前终端窗口有效。安装完成后，如果你希望以后brew install也走镜像，需要把HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN写进~/.zshrc或者~/.bash_profile。但HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE建议只在安装阶段用，装完之后留着反而可能在brew update时造成分支不一致的问题。

3.2 安装脚本本身拉不下来怎么办

还有一个坑：安装脚本本身也是从远端获取的。如果这一步就走不通，那就先把脚本下载到本地，检查一遍再执行。这样做的另一个好处是你可以先读一遍脚本内容，确认它要动哪些目录。

# 先下载脚本到本地，不直接执行 curl -fsSL <安装脚本地址> -o ~/brew-install.sh # 养成习惯，执行前看一眼前几十行 head -n 60 ~/brew-install.sh # 确认没问题再运行 /bin/bash ~/brew-install.sh

脚本地址以官方仓库或镜像站当期说明为准。我个人的习惯是，任何以"直接管道进 bash"形式给出的命令，我都会先落到本地看一眼。这不是不信任谁，而是这个习惯帮我避过好几次"脚本参数变了但文章没更新"的坑。

3.3 Git 侧的调优参数

换源解决的是"距离"问题，还有几个 Git 参数能缓解"长连接脆弱"的问题。这些参数的作用是让 Git 在传输不顺畅时更宽容一些：

# 加大 HTTP 缓冲区，减少大对象传输时的分片问题 git config --global http.postBuffer 524288000 # 把低速中断的门槛调低，避免速度波动时被判定为"卡死"而主动断开 git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999 # 关闭压缩，用带宽换 CPU，某些链路上反而更快 git config --global core.compression 0

关于http.postBuffer，我要补充一句实话：这个参数在社区里被过度神化了。它主要影响的是推送大对象时的分块行为，对git clone的帮助有限。真正有效的往往是把lowSpeedLimit这类"多久没速度就断开"的判定关掉，因为很多 clone 失败并不是真断线，而是速度掉到阈值以下被 Git 主动放弃了。

注意：这几个参数是全局生效的，会影响你机器上所有的 Git 仓库。如果你的日常开发对 Git 配置有特殊要求，建议改完之后记录一下改了什么，方便以后回滚。

4. 完整实操：从清理到验证

理论讲完了，这一节走一遍完整流程。我会按"先体检、再清理、后安装、再验证"的顺序来，每一步都说明为什么这么做。

4.1 动手前的三项体检

不要一上来就跑安装脚本。先花两分钟做三项检查，能避免 80% 的重复失败。

# 检查一：Command Line Tools 装好了没 xcode-select -p # 正常会输出类似 /Library/Developer/CommandLineTools # 如果报错或者输出为空，先执行： xcode-select --install # 检查二：Git 是否可用，版本是否太老 git --version # 检查三：磁盘剩余空间 df -h /

xcode-select -p这一项我要多说两句。很多人的失败其实发生在更早的阶段——安装脚本触发了工具链安装弹窗，用户点了"取消"，脚本继续往下跑，结果在需要编译或者需要 Git 的时候挂了。所以如果输出为空，请把xcode-select --install弹出的安装流程走完，看着它显示"已完成"再继续。

4.2 清理上一次失败的残留

这是整篇文章里我认为最重要的一步。失败过的机器上，/usr/local/Homebrew目录往往已经被创建了一部分，里面是空的或者残缺的仓库。安装脚本第二次运行时，遇到已存在且非空的目录，行为和第一次完全不同，很容易出现"目录冲突"类错误。

清理的方式有两种：

方式一：用官方卸载脚本（推荐）

/bin/bash -c "$(curl -fsSL <官方卸载脚本地址>)"

方式二：手动清理（脚本拉不下来时）

# 先看清要删什么，别闭着眼睛 rm ls -la /usr/local/Homebrew 2>/dev/null ls -la /opt/homebrew 2>/dev/null # 删除 Homebrew 相关目录 sudo rm -rf /usr/local/Homebrew sudo rm -rf /usr/local/Caskroom sudo rm -rf /usr/local/Cellar sudo rm -rf /opt/homebrew # 删掉可能的软链接 sudo rm -f /usr/local/bin/brew

清理完还要检查 shell 配置文件里有没有残留的 PATH 设置：

# 看看 zshrc 里有没有 Homebrew 相关的行 grep -n -i "homebrew\|/opt/homebrew\|/usr/local/bin/brew" ~/.zshrc

如果有，把这些行注释掉或者删掉。留着不会立刻报错，但下次装完容易出现 PATH 里有两份路径、命令指向错误的问题。

4.3 执行安装并观察输出

环境变量配置好、残留清理干净之后，就可以跑了。这里我强烈建议不要关终端窗口、不要中途按 Ctrl+C，把输出完整看完。

# 第一步：设置镜像相关的环境变量（路径以镜像站当期说明为准） export HOMEBREW_BREW_GIT_REMOTE="https://<镜像站>/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://<镜像站>/homebrew-core.git" export HOMEBREW_API_DOMAIN="https://<镜像站>/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://<镜像站>/homebrew-bottles" # 第二步：执行安装脚本 /bin/bash -c "$(curl -fsSL <安装脚本地址>)"

安装过程中终端会输出几个关键阶段：==> Checking for sudo access、==> This script will install:、==> Downloading and installing Homebrew...。看到最后那行滚动的进度说明主仓库正在拉取，这一步通常一两分钟能过。如果它在这里停了很久，说明远端还是不通，回到第 2 节用git clone --depth=1手动测一下目标地址。

安装完成后，脚本会提示你执行两条命令把brew加进 PATH。Apple Silicon 和 Intel 的路径不一样，脚本会直接告诉你，照抄就行，通常是这样的形式：

# Apple Silicon 常见形式 echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc eval "$(/opt/homebrew/bin/brew shellenv)" # Intel 常见形式 echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc eval "$(/usr/local/bin/brew shellenv)"

写完记得source ~/.zshrc或者干脆开一个新终端窗口。

4.4 验证与收尾

装完不代表结束，验证环节能帮你提前发现问题。

# 看版本 brew --version # 看环境配置，重点确认各个 Domain 变量是否按预期生效 brew config # 体检，Homebrew 自己会给出建议 brew doctor

brew config的输出信息量很大，值得逐行看一遍。它会显示HOMEBREW_PREFIX、HOMEBREW_CELLAR、HOMEBREW_REPOSITORY，以及你设置的那几个 Domain 是否被识别。如果发现HOMEBREW_BOTTLE_DOMAIN还是默认值，说明环境变量没写进配置文件，只存在于某个已经关掉的终端里。

brew doctor的输出有时候会有一大堆 Warning，不用慌。我通常只关注它给出的"建议操作"里排在前面几条，后面的多是可选提醒。但如果你看到关于/usr/local权限的警告，那就需要认真处理了，说明前面清理得不够干净。

最后跑一个真实安装测试一下整条链路：

# 装个小工具试试，比如 jq 这种体积很小的 brew install jq # 确认能正常调用 jq --version

如果这一步顺利，说明从元数据获取到 Bottle 下载的链路都通了，整套环境算是真正可用了。

5. 常见问题速查与避坑经验

到这一步，大部分人的问题应该已经解决了。但实际操作中还有一些反复出现的细节，我整理成表格和几条经验，方便你对照排查。

5.1 问题排查速查表

5.2 我自己踩过的几个坑

第一个坑：反复重试同一条命令。早期的我做的最蠢的事，就是失败之后直接按上箭头重跑。git clone没有断点续传，重跑一百次也是从头拉一遍，成功率不会因为重试次数变高。真正改变结果的是换一个更近的源，或者缩短要拉取的数据量。

第二个坑：用sudo装 Homebrew。网上有文章说"加 sudo 就能解决权限问题"，这是绝对的错误方向。加了sudo，仓库文件归属会变成 root，之后所有brew install都要带sudo才能写入，整个环境就废了。正确的做法是让安装脚本以普通用户身份运行，脚本自己会用sudo处理它需要处理的那几个系统级目录。

第三个坑：把镜像变量永久写进配置文件。我在一台机器上把HOMEBREW_CORE_GIT_REMOTE写进了~/.zshrc，用了大半年没出问题。后来镜像站调整了仓库地址，brew update开始报错，而且报错信息完全不提环境变量，我排查了很久才想起来是自己写死的那行。从那以后我的原则是：安装阶段的变量只用在安装阶段，运行期的 Domain 变量才写进配置文件。

第四个坑：忽略brew doctor里的路径警告。有一次我装完之后没管警告，用了两周之后发现某些工具的命令行版本和预期不一致。查下来是 PATH 里同时存在两个 Homebrew 路径，旧的那份虽然已经被删了目录，但 PATH 里还留着，导致某些命令走了不可预期的位置。这类问题不会立刻暴露，但会在某天以"莫名其妙的诡异现象"出现。

最后分享一个诊断的小习惯：遇到任何 Git 相关的失败，先用最小化命令复现。不要直接跑完整安装脚本，而是把失败的那条git clone单独拎出来，换个目标目录、加--depth=1、加-v看详细输出。安装脚本的输出很'礼貌'，很多底层错误被它吞掉了；而git clone -v会把实际的连接过程一步步打出来，卡在哪一环一眼就能看到。我自己用这个习惯定位过好几次问题，包括 TLS 握手失败、解析到错误地址、以及服务端返回 5xx 这类脚本层面完全看不出来的原因。

后续如果还想再省事一点，可以把镜像相关的 Domain 变量整理成一个小脚本，新机器上装完系统直接跑一遍。我现在给朋友装机器就是这么干的：一个setup-brew.sh，里面包含环境变量、安装、PATH 写入、以及几个常用工具的一次性安装。写一次，之后每台新机器省下十几分钟。这个思路同样适用于其他需要从远端拉取的工具链，核心逻辑都是"就近取源 + 减少传输量 + 失败可复现"。