Homebrew 安装全攻略：原理、镜像源与排查思路

装 Homebrew 这件事，说简单也简单，说难也难。我见过不少人卡在安装命令上，屏幕一停在Downloading...，几分钟没动静，最后要么关掉终端放弃，要么反复重试同一行命令碰运气。最近帮一个朋友装，又碰到一模一样的问题，这才觉得应该把整个安装过程、背后的原理、常见报错的排查思路一次讲透。

Homebrew 是 macOS 上使用率最高的包管理器，装好之后，wget、jq、tree、nginx、node 这些常用工具都能用brew install一条命令搞定，不用自己编译源码，也不用到处找安装包。但它的安装过程确实劝退了一批人：官方脚本要从网上拉取安装文件，还要用 git 把仓库同步到本地，只要网络这一环不顺，整体就失败。这篇文章会从安装脚本到底在做什么讲起，把目录权限、镜像源配置、安装后的验证方法、常见报错排查链路一次说清楚。不管你是第一次装，还是装到一半卡住，跟着走基本能解决。

1. 安装前先搞清楚两件事：目录和权限

1.1 为什么官方脚本要求先有命令行工具链

Homebrew 本身是用 Ruby 写的脚本，它的启动和运行并不复杂，但装完依赖包之后，经常需要编译源码，所以 macOS 上必须有 Xcode Command Line Tools——也就是命令行开发者工具集，里面包含 clang、git、make、curl 这些最基础的编译和网络工具。

很多人装的时候没有意识到，Homebrew 安装脚本会自动触发这个工具的安装弹窗。脚本在xcode-select环节检测到系统里没有工具链，就会弹窗让你安装，等它装完才继续走后面的流程。我遇到过一种情况：弹窗出来之后被直接关掉了，安装脚本就一直停在那里不动，没有任何明确的报错，看起来就像卡死。实际上只要重新跑一遍脚本，把工具链补装好，就能继续。

如果你打算自己先装，直接执行下面的命令，等它走完就行：

xcode-select --install

装完后可以用xcode-select -p验证，如果输出的是一个路径（比如/Library/Developer/CommandLineTools），就说明工具链已经就位。

1.2 Apple Silicon 和 Intel 的安装目录差异

Homebrew 在两种芯片架构下的默认安装目录完全不同：

芯片架构	默认安装目录	说明
Apple Silicon（M系列）	/opt/homebrew	脚本自动创建目录并设置属主
Intel	/usr/local	目录通常已存在，但属主是 root，需要改权限

这个差异是很多权限问题的根源。Intel 机器上的/usr/local目录在较新系统里默认存在，但普通用户没有写权限，所以安装时需要输入 sudo 密码，脚本用 root 身份把目录属主改成当前用户。Apple Silicon 机器上/opt目录通常不存在，脚本需要创建/opt/homebrew，这同样需要 root 权限。

理解这个区别能帮你快速定位问题：装完 brew 后如果出现Permission denied，基本就是目录属主不对；在 M 系列芯片机器上发现 brew 被装进了/usr/local，那说明终端很可能跑在 Rosetta 模式下。

我这里有个建议：装之前先执行uname -m看一眼架构。看到arm64说明当前 Shell 是原生 ARM 模式，看到x86_64则是 Rosetta 模式。安装之前确认这一点，能省掉后面很多定位问题的力气。

1.3 老系统就别折腾了

Homebrew 对 macOS 版本有要求，建议使用新一点的系统版本。老系统上即使安装命令走通了，后面编译软件包时也很容易出现build failed或缺少某个系统库的报错。不要指望用 Homebrew 解决一切旧系统问题，它的策略就是紧跟新版系统走。

2. 官方安装命令到底在干什么

2.1 一条命令拆开看

官方让你跑的命令大致是这样：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

这段命令的逻辑并不复杂：用curl把远程的install.sh脚本下载下来，直接交给bash执行，整个过程不落盘。好处是一条命令完成全部操作，坏处是一旦curl阶段网络超时，整条命令就直接失败，而且失败的原因藏在网络层，用户看到的只有一串Failed to connect。

2.2 安装脚本的七个步骤

我把整个安装脚本的流程拆解过，核心步骤其实很固定：

1. 检查系统版本、CPU 架构、是否已有旧版本 Homebrew。
2. 检查是否已有目标目录，判断是全新安装还是升级。
3. 用 sudo 创建目录并设置属主。
4. 从远程仓库拉取 Homebrew 主代码库。
5. 创建符号链接、写入 Shell 环境配置。
6. 执行brew update更新索引。
7. 输出Installation successful。

第 4 步是整个安装最容易卡住的地方。脚本默认从官方源拉取代码，在国内网络环境下经常断断续续，这也是后面要讲镜像的核心原因。

2.3 为什么需要输入 sudo 密码

创建/opt/homebrew目录、给/usr/local目录授权当前用户，这两个动作都属于系统级操作，普通用户没有权限，必须用 sudo。Homebrew 的官方设计原则是：安装完成后，当前用户拥有整个 Homebrew 目录，之后的日常操作都不要再使用 sudo。

这里有一点很多人会忽略：sudo 密码输入完成之后，脚本会花一段时间配置目录权限。如果你这个时候中断安装，目录可能处在“已创建但属主不对”的状态，后面重装时反而会多出一些权限报错。所以我一般建议，开始安装之后就让它跑完，不要中途去动终端。

2.4 脚本执行到一半失败了，能不能重复执行

可以，而且这是很多人不知道的一个特性。安装脚本本身带有幂等设计：目录已存在就跳过创建，仓库已存在就执行更新而不是重新 clone。所以哪怕你装到一半报错退出，只要把核心问题（比如网络）修复，再跑一遍同一行命令，它不会从零开始，而是接着上次的进度继续。

3. 国内网络环境下怎么装：镜像脚本和换源三板斧

3.1 安装阶段最快的办法：直接用镜像站提供的安装脚本

如果你已经试过官方命令，发现一直卡在下载或者报连接失败，那就别反复重试了，直接换镜像源方案。

国内几大开源镜像站点都同步了 Homebrew 所需的仓库文件，并且提供了现成的install.sh安装脚本。你只需要去镜像站首页找到 Homebrew 栏目，复制里面的安装命令执行即可。这些脚本的行为和官方脚本一致，区别只是把下载地址和 git 远程地址替换成了镜像地址，安装过程的体验会顺畅很多。

关于具体域名，我这里不逐个罗列，因为镜像站比较多，不同站点的路径也有差异。去镜像站首页的 Homebrew 栏目里，通常能看到明确的安装命令和配置说明，照着复制就行。

3.2 装完后把源固定到本地配置

不管用哪种方式装完，装好之后第一时间要做的是把源配置固化到 Shell 配置文件里。我的推荐做法是打开~/.zshrc，追加下面这些内容：

export HOMEBREW_BREW_GIT_REMOTE="https://你的镜像站/git/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://你的镜像站/git/homebrew-core.git" export HOMEBREW_BOTTLE_DOMAIN="https://你的镜像站/homebrew-bottles"

三个变量各自管一件事：

• HOMEBREW_BREW_GIT_REMOTE：Homebrew 主仓库的 git 地址。
• HOMEBREW_CORE_GIT_REMOTE：核心软件仓库的 git 地址。
• HOMEBREW_BOTTLE_DOMAIN：预编译二进制包的下载地址。

后两者特别容易混淆。CORE_GIT_REMOTE管的是软件仓库索引，BOTTLE_DOMAIN管的是直接下载的二进制包。它们的路径格式不一定一样，具体要以镜像站首页的说明为准。只配前两个不配第三个，你安装具体软件时下载 bottle 还是会走官方地址；只配第三个不配前两个，brew update又会卡住。三件套最好来自同一个镜像站，避免仓库和包下载地址分属两处导致版本不一致。

3.3 已经用官方仓库装了一半，如何挽救

如果你已经开始安装，卡在Cloning into ...或者下载步骤，可以直接按Ctrl+C中断安装，然后进入对应目录，手动修改 git 远程地址。以卡在 homebrew-core 仓库为例：

cd /opt/homebrew/Library/Taps/homebrew/homebrew-core git remote -v git remote set-url origin https://你的镜像站/git/homebrew-core.git

然后重新执行安装脚本，它会接着把剩下的步骤走完。

不过说实话，对于大多数人来说，手动修补半截仓库的性价比不高，尤其是如果你不确定当前进度到了哪一步。如果安装目录里已经残留了大量不完整文件，直接把残留目录清理掉，再用镜像安装脚本重装一次，反而更快更干净。

3.4 换源之后一定要做验证

换源这个动作本身不复杂，但很多人换完就完事了，也不检查有没有生效。我的习惯是两步验证：

brew config brew doctor

brew config的输出里会列出HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_BOTTLE_DOMAIN这些字段，逐一确认已经变成镜像站地址。brew doctor检查仓库状态，如果输出里有Uncommitted changes或者remote not found之类的提示，说明源配置有问题，需要处理。

另外，新版本的 Homebrew 还引入了HOMEBREW_API_DOMAIN这个变量，用来控制公式 API 和 JSON 索引的下载地址。如果你的镜像站支持，建议也一并配置，可以让brew search、brew info这类命令更快。

4. 装完后的首轮体检：几个命令让环境更稳

4.1 验证核心命令

安装完成后，先跑这几条命令确认基本状态：

brew --version which brew brew config brew doctor

which brew的输出最直观：Apple Silicon 机器上正常是/opt/homebrew/bin/brew，Intel 机器上是/usr/local/bin/brew。如果输出路径没有出现，或者出现/bin/bash之类的异常结果，说明 PATH 配置有问题。

4.2 PATH 配置不生效的尴尬

安装脚本会自动往~/.zprofile里写入一行环境变量加载代码，类似这样：

eval "$(/opt/homebrew/bin/brew shellenv)"

这设计本身没毛病，但实际使用中经常出问题。很多人用的终端工具启动时并不一定会加载~/.zprofile，或者你是在 tmux 子会话里运行命令，PATH 没有刷新。结果就是终端里输入brew，直接报command not found。

最简单的方法是先手动验证一下：

echo $PATH | grep homebrew

如果没有输出，说明 brew 的路径不在 PATH 里。解决方法不难：把上面那行eval同时加到你自己终端实际读取的配置文件里。用 zsh 就加进~/.zshrc，用 fish 就加进~/.config/fish/config.fish。加完之后重开一个终端窗口，再执行which brew验证。

4.3 首次 brew install 的预期时间

配置好源之后，装一个常见软件包是检验配置是否生效的最佳方式。拿 wget 举例：

brew install wget

如果 bottle 域名配置正确，下载速度一般会很快，几十秒内就能完成。你可以在终端日志里看到下载 URL，如果显示的是镜像站地址，说明配置生效了；如果看到的是官方二进制库地址，那说明HOMEBREW_BOTTLE_DOMAIN没设置成功。

4.4 几条最常用的命令速记

装好 Homebrew 之后，日常最常用的命令其实就那么几个：

命令	作用	示例
brew install <包名>	安装软件包	brew install jq
brew uninstall <包名>	卸载软件包	brew uninstall jq
brew list	列出已安装的包	brew list
brew search <关键词>	搜索可用包	brew search node
brew info <包名>	查看包详情	brew info node
brew cleanup	清理旧版本文件	brew cleanup
brew update && brew upgrade	更新自身并升级所有包	brew update && brew upgrade

建议把这张表保存成便签，用几次基本就记住了。

5. 踩坑实录：从卡死到装完的完整排查链路

5.1 场景A：curl 直接报连接失败

现象：执行安装命令，几秒后终端输出Failed to connect ... port 443: Connection refused。

根因是当前网络环境无法稳定访问官方下载服务器。这种情况不是你命令打错了，也不是终端坏了，就是地址连不通。

排查链路：

1. 先单独测试连通性，确认是不是偶发问题：

curl -I https://raw.githubusercontent.com

如果同样立即失败，说明不是偶发，是持续性的网络问题。

2. 不要反复重试官方地址，没意义。每次重试只是让curl再去碰一次同样不通的地址。

3. 直接换成镜像站安装脚本执行。这一步通常能彻底绕开问题。

5.2 场景B：权限报错

现象：安装过程中出现类似Permission denied @ dir_s_mkdir - /usr/local/Cellar或Operation not permitted。

根因很统一：目标目录的属主不是当前用户。排查思路如下：

1. 先查看目录属主：

ls -l /usr/local | head

如果目录属主是 root，而当前用户不是 root，写操作就会失败。

2. 如果只是临时需要，可以用 sudo 修改 Homebrew 相关目录的属主：

sudo chown -R $(whoami) /usr/local/Cellar

但这里我要特别提醒：不要对整个/usr/local目录执行chown -R。这个目录在 macOS 上不只是 Homebrew 在用，系统和其他工具也可能在里面写文件，整体授权给当前用户会造成一些意料之外的麻烦。如果你刚装了一半发现权限不对，最省心的方式是卸载重装，而不是大规模修权限。

3. Homebrew 官方哲学是“当前用户拥有整个 Homebrew 目录”，后续日常操作不要再用 sudo。如果你发现某个命令加了 sudo 才能跑，说明你的目录属主配置有问题，优先修属主，而不是以后都靠 sudo 硬撑。

5.3 场景C：Apple Silicon 机器上装到了 /usr/local

现象：M 系列芯片电脑上，安装路径出现了/usr/local/bin/brew。

根因是当前终端会话以 x86_64 兼容模式运行，脚本检测到的架构信息偏向 Intel，于是选择了 Intel 的安装路径。排查办法：

1. 执行uname -m，如果输出x86_64，说明当前会话确实跑在 Rosetta 模式下。
2. 检查你的终端工具是否被强制设置为“使用 Rosetta 打开”。在终端 App 的“显示简介”里通常有一个“使用 Rosetta 打开”的勾选项，去掉勾选后重新打开。
3. 如果已经装错位置，建议卸载后重新以原生 ARM 架构安装。

这个问题出现频率不高，但一旦出现，症状很迷惑，因为命令能跑，但一切都跑到 Intel 分支上去了。

5.4 场景D：卸载重装

如果你已经把环境折腾得很乱，最快的解决办法是用官方卸载脚本彻底清理，然后重装。

大致流程：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

卸载脚本会检测目录里已有的 Homebrew 文件，列出后询问是否删除。确认删完，重启终端，再执行which brew，没有输出就说明清理干净了。之后再用第一节和第三节讲的镜像流程重新安装。

5.5 一个真实案例的完整过程

最后分享一个我实际遇到的案例。某台机器装 Homebrew 时一直卡在Cloning into '/opt/homebrew/Library/Taps/homebrew/homebrew-core'...，进度条就是不动。

我判断这是 git clone 远程仓库环节卡住，不是终端无响应。当时的处理过程是：

1. 按Ctrl+C中断安装。
2. 进入出问题的目录：cd /opt/homebrew/Library/Taps/homebrew/homebrew-core。
3. 执行git remote -v，确认远程地址指向官方地址。
4. 执行git remote set-url origin https://你的镜像站/git/homebrew-core.git。
5. 重新执行安装脚本，这次没有再卡住，几分钟内装完。

这个案例的思路可以复用：报错发生在哪个仓库，就去哪个仓库目录里改 remote 地址。不要盲目删掉整个目录重新来过。

另外说一句，Homebrew 新版已经把很多 tap 仓库合并到了 API 接口里，如果提示找不到某个 tap，优先检查HOMEBREW_API_DOMAIN是否配好。

6. 安装之外：让 Homebrew 长期好用的一些习惯

6.1 固定频率做一次整体更新

brew update && brew upgrade会更新 Homebrew 自身和所有已安装软件包。但我个人习惯在升级前先跑brew outdated看一眼哪些包准备升级，再决定要不要执行升级。尤其是项目依赖里有固定版本要求时，直接brew upgrade可能会把关键依赖升到一个不兼容的版本。

6.2 不要碰 sudo

这条值得反复强调：Homebrew 日常操作不要使用 sudo。用 sudo 安装的包，文件属主变成 root，下次升级时就会报权限错误，而你已经忘了当初为什么加 sudo。记住 Homebrew 的设计就是给单个用户使用的，除非你要在 CI 服务器上做全局配置，否则任何让你用 sudo 的教程都是坑。

6.3 配置文件放对位置

镜像源的环境变量，建议写到自己的~/.zshrc里，不要写到/etc/zshrc。全局配置文件会影响所有用户，而你无法保证其他人也需要你的镜像配置。另外注意检查有没有重复写入，比如~/.zprofile和~/.zshrc各有一份eval "$(/opt/homebrew/bin/brew shellenv)"，重复执行会在 PATH 里累积重复路径，出问题的时候比较难排查。

6.4 常用的“开胃”包

装好 Homebrew 之后，我一般先装这几个工具，纯个人推荐：

brew install wget jq htop tree git-lfs ripgrep

• wget：命令行下载工具
• jq：JSON 处理工具
• htop：系统资源监控
• tree：可视化目录结构
• git-lfs：大文件版本管理插件
• ripgrep：极快的文本搜索工具

这些都是高频实用工具，能把终端体验提升一个档次。

6.5 装包前后留意依赖链

有些软件会带很多依赖。比如装编辑器类工具时，经常顺带装上 Lua、Python 解释器，这是正常现象，不必担心。但要注意的是，升级时brew upgrade会把依赖一并升级，如果磁盘空间紧张，记得定期执行brew cleanup，清理旧版本文件。

6.6 关于长期体验

我自己用镜像配置加 API 域名这套方案，已经一年多没动过源相关配置了。Homebrew 的日常体验很简单：需要什么工具，一条brew install搞定，不用再开浏览器找安装包，不用手动管理升级。前期花一点时间把源和权限逻辑理顺，后面基本可以不再折腾。如果你正在被安装过程折磨，试着按这篇文章的思路重新走一遍，大概率能顺利跑通。