拿到一台新电脑、重装了系统、或者帮朋友处理开发环境，很多人第一件事就是装Homebrew。作为macOS上最常用的包管理器，它解决的是“装软件像装系统依赖一样简单”这件事：一条命令装好Node、Git、OpenSSL这些基础工具，还能管理更新、清理旧版本。这篇文章不打算复读官网文档，我会把从环境检查、安装命令、镜像加速、环境变量到卸载清理，以及那些年踩过的坑，完整串一遍。适合刚接触macOS开发的新手，也适合给同事写“安装指南”时懒得重新调研的老手。
1. 安装前的准备工作与环境检查
不少人在终端里粘贴安装命令，结果跑了十几分钟报错，最后发现是系统环境不对。这节先花三分钟把前置条件查清楚，能省掉后面一大半的麻烦。
1.1 为什么需要 Xcode Command Line Tools
Homebrew的安装脚本在编译源码、拉取仓库、处理依赖时，会高频用到C语言编译器和系统头文件。macOS虽然自带了一部分开发工具，但默认不完整，所以安装脚本往往会在开始时自动尝试安装Command Line Tools。
很多新手在这里卡住，是因为弹窗出现后没等它装完就直接关掉，或者网络不好导致下载失败。Command Line Tools本身是一个约1GB左右的包，安装过程没有图形进度条，终端里只会看到“Installing...”之类的提示，有些人误以为卡死了就强行中断。
如果系统里还没装，可以手动执行：
xcode-select --install装完后确认编译器可用：
gcc --version能正常输出版本号，说明编译链路没问题。
1.2 芯片架构与系统版本的判断方法
Homebrew在不同芯片上的安装路径完全不同，先看清楚自己机器是哪一种架构，后面才不至于把路径配错。
uname -m输出arm64表示Apple Silicon机型，安装路径默认是/opt/homebrew；输出x86_64表示Intel机型，默认路径是/usr/local。这两条路径的区别非常关键，配置环境变量、设置PATH时写错一个，就可能导致brew command not found。
另外确认系统版本支持：我个人建议macOS 12以上直接用最新版Homebrew，如果是老系统，还要额外关心系统自带的Ruby版本和curl版本。可以顺手看一下：
sw_vers curl --versioncurl版本不能太老，否则访问HTTPS资源时可能出现证书校验问题。检查完这些，后面的安装流程基本不会因为环境问题半路翻车。
2. 最稳妥的官方安装流程与原理拆解
环境准备就绪后，就可以走官方安装脚本了。这节不光给出命令，我会把脚本背后的执行逻辑拆开讲清楚，这样你遇到报错时才知道它在哪一步挂掉的。
2.1 官网推荐命令的完整执行细节
官方安装命令是一行通过curl执行的bash脚本：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"拆开来看：curl -fsSL里的-f表示遇到HTTP错误就失败退出，-s是静默模式，-S让静默模式下仍然显示错误信息，-L是跟随重定向。整个命令的意思是“拉取远程安装脚本，然后用本机bash执行它”。
执行后脚本会先做一系列检查，包括：当前用户权限、系统版本、Command Line Tools是否已安装、芯片架构。然后它会在/opt/homebrew或/usr/local下创建目录骨架，并开始从远程仓库拉取release文件。整个耗时取决于网络条件，快则两分钟，慢则半小时。
执行过程中脚本会询问是否继续，并提示将要创建目录的位置。这里建议输入管理员密码后才能继续，因为Homebrew需要写入系统级目录。如果不想交互式等待，可以在执行前设置环境变量NONINTERACTIVE=1，适合批量部署场景。比如：
NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"2.2 安装脚本到底做了什么，每一步的用途
很多教程只告诉你粘贴命令，不问为什么。实际上理解脚本行为对排查问题特别有用。
脚本的第一步是“前置校验”：确认你不是root用户。Homebrew明确要求不要用root运行安装，因为包管理器的后续操作都会以普通用户执行，避免权限混乱。
第二步是“目录创建”：在选定路径下创建bin、etc、lib、include等目录。这些目录存放后来安装的各类软件和库文件。
第三步是“下载并解包”：从GitHub仓库拉取Homebrew本体到目标目录。如果这一步网络失败，通常会报curl: (7) Failed to connect to raw.githubusercontent.com port 443，这也是大陆网络环境最常见的错误。
第四步是“设置目录权限”：确保当前用户对Homebrew安装目录拥有完整读写权限，而无需借助sudo。
最后一步是“后续提示”：脚本结束时会提示你执行两条命令，把Homebrew的bin目录加入PATH环境变量，并提示安装完成。对Apple Silicon机型来说，就是：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"执行后当前终端立刻能识别brew命令。如果这是新开的终端，那只需要第一条写入配置文件的命令，以后每次打开都自动生效。
3. 网络受限环境下的加速安装方案
官方脚本默认从GitHub下载，遇到网络波动或访问不畅时，要么卡在下载阶段，要么校验文件哈希失败。这节讲怎么合理利用镜像资源，既保速度又不牺牲安全性。
3.1 安装阶段直接换源的两种做法
第一种做法是直接通过环境变量指定安装源。Homebrew安装脚本支持通过HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE等环境变量指定仓库地址。在执行官方安装命令前，先导出这些变量，比如：
export HOMEBREW_BREW_GIT_REMOTE="https://某个镜像地址/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://某个镜像地址/homebrew-core.git" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"这样脚本会把本应访问GitHub的仓库请求指向镜像，安装速度通常快很多。缺点是需要对镜像的稳定性有一定把握，如果镜像本身挂了，安装一样失败。
第二种做法是“先稀里糊涂装上，再整体换源”。具体来说，先随便下载一份安装脚本看它需要哪些固定仓库，或者干脆用官方脚本碰碰运气，等装好后统一把brew和homebrew-core的remote换成镜像地址。这个方法的好处是后续所有操作都走镜像，不用每次安装前都导环境变量。
我个人的建议是：如果你经常遇到安装中断，优先用第一种做法装本体；装好之后再用git remote set-url持久换源。
3.2 安装后的持久换源配置方法
Homebrew本身是git仓库，所以源地址就是git的remote地址。装好后可以通过下列命令查看当前源：
cd "$(brew --repo)" && git remote -v cd "$(brew --repo homebrew/core)" && git remote -v要换成镜像源，直接修改remote地址：
cd "$(brew --repo)" git remote set-url origin https://某个镜像地址/brew.git cd "$(brew --repo homebrew/core)" git remote set-url origin https://某个镜像地址/homebrew-core.git换完源后建议立刻执行：
brew update确认能正常更新到最新版本。这里有个细节：新版Homebrew把核心公式库拆成了独立仓库，旧版还需要额外配置homebrew-cask和homebrew-bottles。如果你需要安装图形化应用（比如通过brew install --cask安装浏览器），对应的cask仓库也要换源，方法跟上面一样，只是路径换成cask仓库。
提示：镜像不等同于“零风险”。尽量选择维护活跃、同步频率高的镜像，并定期关注其公告。任何镜像都有延迟，偶尔出现“找不到某个版本”的情况，回到官方源临时拉一次就好。
4. 安装完成后的验证、环境变量与卸载清理
装好只是第一步，能不能在终端里顺畅用起来，环境变量和路径检查是关键。有人装完后直接关闭终端，再打开时发现brew命令又不见了，原因就是环境变量没写入配置文件。
4.1 验证环境变量与核心命令
以Apple Silicon机型为例，官方脚本结束后会提示你把/opt/homebrew/bin加入PATH。上面已经给出写入~/.zprofile的命令，但我更推荐直接写入~/.zshrc，因为zprofile只在登录shell时加载，实际开发中偶尔会遇到奇怪的不生效问题。
操作步骤：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc之后分别验证：
which brew brew --version brew configwhich brew输出的路径能反映当前shell实际使用的命令位置。如果输出的是/usr/local/bin/brew而不是/opt/homebrew/bin/brew，说明你安装了多个版本，或者PATH顺序有问题。brew config可以看到Homebrew检测到的系统信息，比如CPU架构、macOS版本、CLT版本、HOMEBREW_PREFIX等，这些信息在报错排查时很有用。
习惯上装完第一个包时，也顺手测试一下包管理器是否全套正常。例如：
brew install wget正常完成且能调用wget，说明软件源、下载缓存、符号链接创建这几条链路都没问题。
4.2 彻底卸载与清理残留文件
卸载Homebrew不那么常用，但遇到“版本混乱想重装”“别人在我电脑上乱搞目录”的时候，干净卸载是必须掌握的技能。官方提供了一个卸载脚本，但我不建议直接执行陌生脚本，更稳妥的做法是手动清理关键路径。
需要删除的核心路径包括：
/opt/homebrew（Apple Silicon）或/usr/local下与Homebrew相关的子目录~/Library/Caches/Homebrew（下载缓存）~/Library/Logs/Homebrew（安装日志）~/.zprofile或~/.zshrc中写入的Homebrew相关配置行
手动删除前先确认路径中确实没有其他重要文件。尤其/usr/local目录在Intel机型上可能还有用户自己放的其他工具，不要整个目录一刀切，而是精确删除Homebrew创建的bin、lib、Cellar、Caskroom等子目录。
如果想用脚本，也只建议在“我刚装完Homebrew，里面没装任何包”这种场景下使用，否则卸载脚本会把包管理器的支持目录全部清除，但那些包本身未必会一并清理干净，反而容易留下孤儿文件。
5. 安装过程中的高频报错与排查实录
这一章是我觉得最值钱的部分。很多问题不是装不上，而是报错信息让人摸不着头脑。我把实际遇到过的、以及同事问过最多的几类问题整理成速查表，再挑几个典型故障展开讲。
5.1 常见报错速查表
| 报错场景 | 常见原因 | 解决思路 |
|---|---|---|
curl: (7) Failed to connect to raw.githubusercontent.com port 443 | 网络无法访问该域名 | 使用镜像源安装，或者配置代理环境变量 |
xcode-select: error: tool 'xcodebuild' requires Xcode | Command Line Tools未安装完整 | 重新执行xcode-select --install |
Error: /opt/homebrew is not writable | 目录权限不对 | 用sudo chown -R $(whoami) /opt/homebrew修正属主 |
fatal: unable to access ... Failed to connect to github.com port 443 | git访问GitHub失败 | 检查网络，或换git remote源 |
Error: Checksum mismatch | 下载文件损坏或镜像源未同步完整 | 清缓存后重试：brew cleanup |
Warning: /opt/homebrew/bin is not in your PATH | 环境变量没配好 | 按上节写入~/.zshrc并source |
Error: The following formulae are missing dependencies | 依赖冲突或更换镜像后未同步 | brew update然后brew install对应依赖 |
5.2 三个典型故障的完整排查过程
第一个典型问题是“安装到一半卡住不动”。现象是脚本长时间停在Downloading Command Line Tools或者Updating Homebrew不动。很多人第一反应是删掉重装，其实先确认网络和CPU占用更靠谱。另开一个终端跑ps aux | grep install看脚本是否仍在运行；再用top确认是否有进程在持续下载。如果进程还在但速度极慢，基本是网络问题，此时中断后换镜像源更有效。
第二个典型问题是“提示当前用户不是目录所有者”。这通常发生在我前面说的“手动创建过/opt/homebrew目录”的情况，或者之前用sudo装过别的工具改变了目录属性。解决办法：
sudo chown -R "$(whoami)" /opt/homebrew执行后重新运行安装脚本即可。不要带着sudo直接跑安装命令，这会埋下很多权限隐患。
第三个典型问题是“安装成功后brew doctor提示警告”。最常见的是“Warning: Some taps in your system have a remote URL that is using a private IP”。原因是有人把镜像源设置成了内网地址，或者之前配过本地代理。如果该镜像确实是自己有意的，可以忽略；如果是残留配置，用git remote set-url换回官方源。brew doctor的诊断信息要一条条看，不要急着全信，也不要全都无视。
5.3 日常使用中的维护习惯建议
最后说几个日常习惯。第一个是“先update再install”。新机器装好Homebrew后，第一次安装任何包之前，先跑brew update更新索引。很多人直接brew install，偶尔会遇到“找不到某个版本”的提示，原因就是索引太旧。
第二个是“不要随意删缓存”。~/Library/Caches/Homebrew里存着下载过的安装包，磁盘空间紧张时用brew cleanup清理，不要手动找到文件删，手动删容易删掉正在使用的部分。
第三个是“对cask应用的更新有没有必要天天执行”。有些人习惯天天brew upgrade，我个人的经验是普通开发机一周一次比较合适，升级前先看一眼brew outdated输出了哪些包，避免某些依赖库被意外升级后导致本地环境失效。
注意：任何时候都不要为了“图方便”直接修改
/usr/local或/opt/homebrew的系统级目录权限。权限设得过宽会引入安全性问题，后期排查问题也更麻烦。让Homebrew保持默认行为，是长期稳定运行最好的方式。
我在实际安装过程中最大的体会是：Homebrew安装并不难，难点全在“环境差异”四个字上。你和你同事的两台电脑可能系统版本、架构、网络环境全都不一样，照抄别人的命令很容易翻车。所以这篇文章写的所有步骤，都建议你根据实际输出来调整。先学会看错误信息，再动手执行命令，远比复制一段命令然后祈祷它成功更可靠。如果装的过程中遇到新的问题，优先跑一遍brew config和brew doctor，大多数谜底都藏在那两段输出里。
