刚拿到新Mac或者重装系统之后第一件事往往是装Homebrew。这个包管理器之于macOS开发者就像apt之于Ubuntu、Chocolatey之于Windows没有它装个nginx、python、git都得手动编译或者拖dmg效率低得让人抓狂。我前前后后在三四台Mac上装过Homebrew有Intel芯片的旧款也有M1、M2的ARM机型可以说把能踩的坑基本都踩了一遍。从最初的raw.githubusercontent.com连接失败到后来curl报错、git克隆超时再到权限问题、目录残留每一步都让人想摔键盘。这篇就把我这几次完整折腾下来的经验做个总结把安装流程、镜像方案、报错排查一次讲透。1. 为什么Homebrew装起来这么麻烦很多刚接触macOS的朋友不理解装个包管理器而已为什么别人一条命令搞定自己执行就各种报错。这里面的水比想象中深得从Homebrew的工作原理说起。1.1 Homebrew到底是什么Homebrew是一个基于Git和Ruby的开源包管理器核心逻辑就是通过脚本把软件源码下载到本地编译安装再把可执行文件软链到系统目录。它跟App Store最大的区别是里面几乎全是开源工具和命令行程序覆盖了开发场景的方方面面。brew install wget、brew install nginx、brew install node这些都是日常操作。它安装软件时主要依赖两个东西一是Git仓库用来拉取软件包的描述信息就是各类Formula二是二进制包或源码包这些文件大多托管在GitHub上。问题就出在这里国内网络环境访问GitHub经常不稳定尤其是大文件下载动不动就超时或断流。很多人安装报错十有八九是卡在从GitHub拉取资源这一步。1.2 Intel Mac和Apple Silicon的安装差异另一个容易让人迷惑的点是芯片架构。Intel Mac和M系列芯片的MacHomebrew的安装路径完全不同。Intel版默认装在/usr/local而Apple Silicon版装在/opt/homebrew。这个差异不仅仅是路径不同还牵扯到环境变量配置、软件编译参数甚至有些Formula对ARM架构支持得不够好装的时候会多编译几步。我在Intel Mac上第一次装Homebrew时根本不知道还有ARM版这回事后来换了M1芯片的机器用默认命令装完发现brew命令找不到检查一圈才发现是因为shell环境变量里还写着/usr/local/bin而实际上Homebrew装在了/opt/homebrew/bin。所以动手之前先搞清楚自己的芯片型号能让后面省掉很多麻烦。系统版本也有影响。Homebrew官方虽然支持macOS 12及以上版本但有些旧系统的依赖库太老Ruby版本也跟不上导致brew安装后运行时报错。我有一台2015年的Intel MacBook Pro停留在macOS Catalina装Homebrew时能装上但一执行brew update就各种Ruby语法报错最后只能手动指定老版本的Homebrew才勉强跑起来。2. 动手前的准备工作很多人喜欢拿到命令就复制粘贴到终端里说实话我也这样干过结果就是反复踩坑。准备工作和安装本身一样重要尤其是网络环境这个隐藏变量。2.1 确认芯片架构和系统版本先执行下面这些命令搞清楚自己的机器是什么情况uname -m sw_versuname -m输出x86_64就是Intel芯片输出arm64就是Apple Silicon。sw_vers能看系统版本。注意Intel Mac上也可能跑到x86_64但M系列上也有可能因为Rosetta转译而显示x86_64为了避免误判再看一下sysctl -n machdep.cpu.brand_string里面写着Apple M1或M2就一目了然。这一步很关键因为它直接决定你后面要用哪个安装脚本、环境变量配到哪里。我在M1 Mac上曾经因为在终端里开了Rosetta模式结果uname显示x86_64差点用Intel的方式装了Homebrew。所以建议在原生终端复制一份终端App勾选“使用Rosetta打开”的就是转译终端里操作。2.2 安装Command Line ToolsHomebrew编译软件时依赖苹果的Command Line Tools这个工具包里包含了git、clang、make等一整套开发工具。检查是否已安装xcode-select -p如果输出/Library/Developer/CommandLineTools说明已经有了。如果提示未安装就执行xcode-select --install系统会弹窗提示安装这个过程可能持续好几分钟依赖网络和苹果服务器的速度。很多人在这一步就直接卡住了弹窗一直转圈没反应。碰上这种情况可以去苹果开发者官网手动下载对应版本的Command Line Tools的dmg包安装完再继续。2.3 网络准备和镜像源选择这一步是重中之重也是绝大多数安装失败的根源。官方安装脚本需要从以下地址拉东西raw.githubusercontent.com拉取安装脚本本身github.com克隆Homebrew核心仓库ghcr.io拉取预编译的二进制包这三个域名在国内的连通质量都不稳定尤其是raw.githubusercontent.com有时连IP都解析不出来。备好一个稳定的网络环境是最省心的方案如果你不方便那就老老实实走国内的镜像源。目前比较成熟的中科大镜像和清华镜像都提供了Homebrew的完整镜像服务。以中科大为例子安装时直接把官方脚本的中科大镜像版拉下来执行就行。这样安装脚本本身、核心仓库、二进制包全都走国内服务器速度和稳定性会好很多。后面我会把具体的命令步骤写出来。3. 完整安装过程实录下面这一段是我反复验证过的安装流程按步骤来大多数机器上都能顺利跑通。用中科大镜像方案作为主路径官方脚本方案作为备用两个我都实测过。3.1 用官方脚本安装网络环境较好的情况如果你的网络环境访问GitHub基本无压力直接执行官方命令是最省事的/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)执行后会出现两个交互提示第一个询问是否确认安装第二个询问Homebrew的安装目录。如果不想交互可以这样NONINTERACTIVE1 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)NONINTERACTIVE1会让脚本跳过所有交互使用默认配置。默认配置下Intel Mac装到/usr/localApple Silicon装到/opt/homebrew非常省心。3.2 用中科大镜像安装国内网络的首选先把安装脚本下载到本地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然后执行安装脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)注意这里脚本本身还是从GitHub拉取但脚本拉完之后里面的brew仓库和core仓库都会走中科大镜像极大降低失败概率。如果连脚本都拉不下来可以先把脚本下载到本地再执行curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o install.sh或者直接用下面这个已经改好镜像的安装脚本/bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)安装脚本执行后它自己会往~/.zprofile里写环境变量。但中科大的脚本还会额外配置HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE这些变量这样后续的brew update、brew install都会自动走镜像不需要每次手动设置。这里有一个细节值得说一下。Homebrew从2021年左右开始核心仓库从homebrew-core迁移到了homebrew/core这种API模式下HOMEBREW_CORE_GIT_REMOTE这个变量在较新的版本里会逐渐失效取而代之的是HOMEBREW_API_DOMAIN。所以如果你装的Homebrew版本很新可能看不到clone homebrew-core的过程了改走API拉取软件包描述。这也是很多老教程失效的原因因为它们还停留在clone homebrew-core的时代。中科大的HOMEBREW_API_DOMAIN配置就是为了适配这个新机制。3.3 安装后的环境变量配置装完之后终端里直接敲brew -v大概率提示找不到命令需要手动加环境变量。Apple Silicon芯片echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel芯片echo eval $(/usr/local/bin/brew shellenv) ~/.zprofile eval $(/usr/local/bin/brew shellenv)这两句的作用是把brew的路径加进PATH环境变量。注意~/.zprofile只对zsh生效如果你用的是bash就改成~/.bash_profile。默认macOS从Catalina开始基本都是zsh了但保险起见可以先echo $SHELL确认一下。确认环境变量生效后跑一下brew -v能输出版本号就说明安装成功了。4. 实战踩坑记录与排查思路这一节是我最想写的因为每个坑都对应一个真实的报错场景也都是新手最容易卡住的地方。4.1 常见报错速查表报错信息可能原因解决方案curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refusedraw.githubusercontent.com访问受限使用镜像安装脚本或配置代理Failed to connect to github.com port 443 after 21001 ms: Connection refusedgithub.com连接超时配置HOMEBREW_BREW_GIT_REMOTE等镜像变量fatal: unable to access https://github.com/Homebrew/brew/: Failed to connect to github.com port 443git克隆失败更换git remote为镜像地址Error: Fetching /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core failed!homebrew-core仓库拉取失败配置HOMEBREW_CORE_GIT_REMOTExcrun: error: invalid active developer pathCommand Line Tools未安装或损坏执行xcode-select --installError: Cant find the library系统缺少依赖brew install时等待编译或安装对应依赖curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to ghcr.io:443ghcr.io连接失败换HOMEBREW_BOTTLE_DOMAIN为镜像地址Permission denied rb_sysopen - /usr/local/Homebrew/.git目录权限问题sudo chown -R $(whoami) /usr/local/Homebrew这张表里的前几条基本涵盖了90%的安装失败场景核心思想就是连不上的资源要么翻过去要么绕道走镜像。4.2 Intel Mac安装不了Homebrew的深层原因“Intel mac 安装不了homebrew了”这个话题的热度一直很高很多老用户发现以前明明一条命令就能装怎么现在就装不上。这里面的原因我认为有三层。第一层是网络因素这个前面说过GitHub访问不稳定是最大的变量。第二层是Homebrew官方做了一些调整比如对macOS版本的要求越来越严格新版本brew源码在macOS Catalina这种老系统上直接跑不起来因为用到了更新的Ruby特性和系统API。第三层是二进制包bottles对Intel Mac的覆盖率很多软件新版本不再提供x86_64的预编译包了brew只能尝试源码编译编译过程更容易失败。我有一台Intel的MacBook Air之前重装系统后想装Homebrew连续报了三次错一次是raw.githubusercontent.com连接失败一次是ghcr.io拉取bottles超时还有一次是系统版本太旧导致的Ruby错误。最后是用中科大镜像指定Homebrew版本才解决。所以如果你的老Intel Mac装不上别灰心多半不是机器的问题是路径没走对。4.3 安装中途卡住怎么办安装脚本执行到一半卡住最常见的是卡在Updating Homebrew...或Cloning into /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core这一步。这个过程实际上是在从GitHub拉取仓库网络差时长达十几分钟都不奇怪看起来就像死了一样。一种处理方式是耐心等待。第一次clone homebrew-core确实需要很长时间一般5到15分钟不等网络稳定的话会看到进度百分比在慢慢跳动。另一种方式直接按CtrlC中断然后把git remote换成镜像源再继续cd /usr/local/Homebrew git remote set-url origin https://mirrors.ustc.edu.cn/brew.git cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git换完镜像后再跑一次brew update速度会明显改善。这一步的原理很简单git remote就是仓库地址换成国内镜像后拉取数据不再走国际链路自然就快了。4.4 卸载残留导致的权限问题如果你之前卸载过Homebrew但没有清理干净再次安装时很可能碰到权限困扰。典型的报错是Error: /usr/local/Homebrew is not writable.这是因为之前安装时用的是sudo某些目录的所有者是root而不是当前用户。解决方案是把这部分目录的所有权拿回来sudo chown -R $(whoami) /usr/local/Homebrew如果提示/usr/local/Homebrew不存在说明卸载时主目录已经被删了但/usr/local/bin或者/usr/local/etc里还有残留的符号链接。可以用ls -l /usr/local/bin/brew看一下如果能看到指向已删除路径的链接手动删掉就行rm -f /usr/local/bin/brew还有一种情况之前的Homebrew装在/opt/homebrew现在换到了/usr/local或者反过来旧路径的符号链接会影响新安装。检查并清理这些残留链接很重要。我记得有一次用户说“Homebrew卸载残留”导致新装后brew命令一直指向旧路径搞得整个系统里有两个brew命令执行结果时对时错。所以安装前一定要确认旧目录清理干净再用which -a brew看看有没有多个brew路径。4.5 Command Line Tools安装失败的处理我遇到过xcode-select --install弹窗后一直卡在“正在下载”的情况等了半小时都没反应。这种时候可以试试清空下载缓存sudo rm -rf /Library/Developer/CommandLineTools sudo xcode-select --reset xcode-select --install如果还是不行就去苹果官方开发者网站手动下载Command Line Tools for Xcode的dmg选择对应macOS版本下载安装。这个方法有效因为很多问题是软件更新服务连接慢导致的。5. 安装成功后的基本操作与优化装好Homebrew不是终点接下来要把它调教得顺手一些。新手最容易忽略的是换源和清理这两件事。5.1 把默认源换成国内镜像如果你是用官方脚本装的建议立刻换成国内镜像否则后续brew install大概率会碰到下载卡顿。在~/.zprofile或~/.bash_profile里追加以下内容export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git清华大学也有对应的镜像地址是mirrors.tuna.tsinghua.edu.cn。我个人习惯用中科大因为它的更新频率和稳定性表现都不错。清华的源也响应快两个选一个即可别两个都混着用容易出奇怪的版本错位。改完环境变量后执行source ~/.zprofile让配置生效然后跑brew update如果输出没有报错说明镜像切换成功。5.2 常用命令速查brew install 软件名 # 安装软件 brew uninstall 软件名 # 卸载软件 brew search 关键词 # 搜索可安装的软件 brew info 软件名 # 查看软件详情 brew list # 列出已安装的软件 brew update # 更新Homebrew自身和仓库信息 brew upgrade # 升级所有已安装软件 brew cleanup # 清理旧版本和缓存 brew doctor # 检查Homebrew环境是否健康brew doctor这个命令值得多说一句它就像Homebrew的体检工具能检测出环境变量配置错误、目录权限问题、残留文件等一大堆隐患。每次碰到疑难杂症先跑一遍这个往往能直接给出解决提示。5.3 提升安装成功率的细节安装软件时如果碰到Download failed或者SHA256 mismatch多半是下载的压缩包不完整。这种时候建议先清缓存再重试brew cleanup rm -rf $(brew --cache)清空缓存后重新执行安装命令会重新下载完整的包。另外brew install默认会先尝试下载bottle预编译包如果平台没有对应的bottle才会走源码编译。编译过程可能耗时很长碰到这种情况可以用brew install --build-from-source强制编译也可以直接用brew install -s。还有一个经验是装软件时尽量一次只装一个别一条命令后跟一堆包名。有些软件依赖关系复杂混装时输出信息又多又乱出了问题不好定位。试过几次你就会发现逐条安装看着慢实际是少走弯路。6. 几条关于安装与使用的个人体会装Homebrew这事说实话不是技术难度有多大而是环境变量太多导致的不确定性太高。不同的芯片、不同的系统版本、不同的网络环境组合出来的问题千奇百怪。我自己踩过一堆坑之后总结出三条比较实用的心得。第一条安装前一定要先确认芯片架构和系统版本再决定用什么方案。别拿到命令就一股脑执行这看起来有点啰嗦实际上能避免大半的无效操作。第二条遇到网络报错先冷静判断瓶颈在哪raw连不上就换镜像脚本git clone慢就换git remotebottle拉不下来就换HOMEBREW_BOTTLE_DOMAIN对症下药比反复重试高效得多。第三条实在不行就从头再来先把旧环境彻底卸载干净再重装。Homebrew卸载是个技术活建议参考官方提供的uninstall脚本真正清干净了再装能少浪费很多时间。另外还有一个小技巧如果你需要在新机器上快速搭好环境可以把常用软件的安装命令写成一个shell脚本比如brew install git、node、python、nginx这些一次性执行完省去一条条敲命令的麻烦。我刚换新Mac时就是这么干的上午拿到机器下午开发环境就齐活了。