1. Homebrew卡在第一步的问题根源1.1 Homebrew是什么为什么mac用户绕不开它Homebrew是macOS上最主流的包管理器地位相当于Linux世界的apt或yum。它解决的核心痛点是macOS不像Linux发行版那样自带一个成熟的软件包管理机制你装个nginx、redis、ffmpeg、wget如果纯手动搞要自己去官网找安装包、手动拖拽、逐个处理依赖库稍微复杂点的软件能把人折腾到怀疑人生。Homebrew把这一整套流程标准化了一条brew install就能把软件连同全部依赖一起装好卸载也干净利落。日常开发里高频用到的git、node、python、nginx、redis、docker-compose甚至一些GUI应用如google-chrome、visual-studio-code都能通过Homebrew统一管理。可以说对于一个mac开发者Homebrew的使用熟练度直接影响日常工作幸福感。网上大量相关热词也印证了这个工具的国民级使用率。但真实情况是很多人卡在了第一步——装不上。新拿到一台Mac、重装系统后、或者从Intel迁移到Apple Silicon之后很多人发现Homebrew就是装不上。报错信息五花八门有的卡在curl下载安装脚本有的卡在git clone仓库有的安装途中直接超时断开。1.2 官方安装脚本为什么总在关键步骤失败要理解怎么装先得知道Homebrew官方安装脚本到底做了什么。拆开看其实就四步第一步从GitHub的raw域名下载install.sh安装脚本第二步脚本内clone两个代码仓库brew本体和homebrew-core公式仓库第三步检查并安装Command Line Tools系统命令行工具第四步从GitHub的release地址下载预编译好的bottle二进制包。问题就出在第一步、第二步和第四步都依赖GitHub的网络链路。国内网络环境下raw.githubusercontent.com的连通性很不稳定git clone大仓库时也经常断流下载bottle时速度更是感人。我自己测试过直连状态下brew install一个300MB的软件下载速度可能只有几十KB每秒中途断开又得从头再来。所以整个行业里的常规解法就一个词换源。把brew仓库地址、homebrew-core仓库地址、bottle下载地址全部指向国内镜像节点。本文要做的就是把这套换源流程自动化一次脚本跑完不用手动设置一堆环境变量。这个方案我在Intel Mac和Apple Silicon的M1、M2机型上都验证过下面的内容会覆盖镜像选型、脚本细节、常见的mac安装homebrew报错处理、Intel Mac专项问题值得直接收藏照做。2. 镜像源选型与整体方案设计2.1 主流国内镜像源横向对比做Homebrew国内镜像本质上是替换三个东西brew.gitHomebrew本体代码仓库homebrew-core.git软件包公式仓库bottles预编译二进制包下载节点国内目前维护质量比较稳定的有清华TUNA、中科大USTC、阿里云三家。我把实际使用中的关键维度整理成了对比表。镜像源brew.githomebrew-core.gitbottles API实测速度稳定性清华TUNA支持支持支持快带宽充足常年在线同步及时中科大USTC支持支持支持快高峰期略有波动维护活跃文档完善阿里云支持支持支持较快偶尔有同步延迟这里要特别强调一个容易踩坑的版本差异Homebrew从4.0开始引入了JSON API机制公式索引默认不再完整clone整个homebrew-core仓库改为通过API动态拉取。这意味着安装配置时除了传统三个变量还要单独配置HOMEBREW_API_DOMAIN把API请求也指向国内镜像。很多老教程或者网上过时的内容只配置了BOTTLE_DOMAIN结果装完发现brew search、brew info这些命令依然卡顿就是因为API请求还在连GitHub。2.2 选型建议与组合方案我个人的推荐优先级是清华、中科大并列第一阿里云作为备选。清华和中科大的同步机制非常成熟遇到404或者回源失败的概率很低。另外有一个很多人忽略的细节——官方安装脚本本身在raw.githubusercontent.com上这一步是整个安装流程里最先卡住的地方。不少人的报错信息里curl连接raw域名直接失败连脚本都拉不下来。网络上的常规处理方式是用镜像站转存的install.sh副本或者提前把脚本下载到本地再执行。我在自动化脚本里会同时处理这个问题这算是我个人在实际操作中认为整个安装流程里性价比最高的一次改动能把成功率提升一大截。如果你所在网络环境对某一个镜像源连接不理想脚本里的三个源可以随时切换地址格式高度一致改起来也简单。我以下默认使用清华TUNA的主配置中科大和阿里云的地址会在代码注释里完整给出。3. 自动安装脚本实战从环境准备到一键完成3.1 安装前的三项环境检查在跑脚本之前强烈建议先花两分钟检查三件事能避免后面大量诡异的问题。第一确认Command Line Tools状态。Homebrew安装时会调用xcode-select检查命令行工具如果没有会自动触发安装。但这一步偶尔会卡住或者反复提示安装。我建议手动先执行一次xcode-select --install如果返回command line tools are already installed说明已经就绪。如果弹出了图形安装窗口等它完整走完再继续。这个过程下载量不小别中途关窗口。第二确认CPU架构。Apple Silicon和Intel Mac的Homebrew默认安装目录完全不同前者是/opt/homebrew后者是/usr/local。后续的PATH配置、目录权限都跟你是什么架构强相关。用一条命令确认uname -m输出arm64就是Apple Silicon输出x86_64就是Intel。第三检查是否有历史安装残留。如果之前安装失败过/opt/homebrew或者/usr/local下可能残留了残缺目录会严重干扰新安装。这个坑在第5章会专门讲这里先记住装之前确认目标目录是干净的。3.2 国内镜像自动安装脚本详解下面这个脚本就是整套方案的核心。它的流程是先用镜像源拉取install.sh安装脚本规避raw域名的不稳定问题然后注入清华镜像环境变量执行官方安装脚本最后自动写入PATH和持久化镜像配置。#!/bin/bash # Homebrew 国内镜像自动安装脚本 # 适用系统macOS 12 / Intel Apple Silicon # 默认源清华大学 TUNA可切换中科大、阿里云 # 1. 下载官方安装脚本优先从镜像站拉取 INSTALL_SCRIPT/tmp/install.sh echo 下载 Homebrew 安装脚本 curl -fsSL -o $INSTALL_SCRIPT \ https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.sh \ || curl -fsSL -o $INSTALL_SCRIPT \ https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh if [ ! -s $INSTALL_SCRIPT ]; then echo 安装脚本下载失败请检查网络后重试 exit 1 fi # 2. 注入国内镜像环境变量 echo 设置国内镜像源 export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api # 中科大源如需切换注释上方并取消注释下方 # 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 # 阿里云源如需切换注释上方并取消注释下方 # export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/brew.git # export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-core.git # export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles # export HOMEBREW_API_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles/api # 3. 执行官方安装脚本 echo 开始执行安装请保持终端活跃 NONINTERACTIVE1 /bin/bash $INSTALL_SCRIPT # 4. 根据架构写入PATH配置 if [ $(uname -m) arm64 ]; then SHELL_RC$HOME/.zprofile BREW_PREFIX/opt/homebrew else SHELL_RC$HOME/.zprofile BREW_PREFIX/usr/local fi if ! grep -q $BREW_PREFIX/bin/brew $SHELL_RC 2/dev/null; then echo 写入brew环境变量到 $SHELL_RC echo eval \\$($BREW_PREFIX/bin/brew shellenv)\ $SHELL_RC fi echo 安装完成验证brew版本 export PATH$BREW_PREFIX/bin:$PATH brew --version # 5. 持久化镜像配置避免后续brew update回源GitHub if ! grep -q HOMEBREW_API_DOMAIN $SHELL_RC 2/dev/null; then echo 写入持久化镜像配置 cat $SHELL_RC EOF # Homebrew 国内镜像配置 export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles EOF fi echo 全部完成新开终端后执行 brew update 验证把脚本保存为install-homebrew-cn.sh然后执行chmod x install-homebrew-cn.sh /bin/bash install-homebrew-cn.sh脚本里有两个关键设计值得说明。第一NONINTERACTIVE1可以跳过官方脚本的交互式确认适合无人值守安装。第一次安装想观察过程的话可以去掉这个变量但自动化安装保留它更省心。第二第一行curl优先从清华镜像的install.sh拉取这步我在前面特别强调了raw域名不稳定是所有安装失败里占比最高的原因绕开它等于成功了一半。3.3 安装完成后的三步验证脚本跑完别急着高兴按下面三步确认真的没问题。第一步验证版本brew --version正常输出版本号说明brew本体已经可执行。第二步确认仓库remote指向镜像cd $(brew --repo) git remote -v正常应该显示清华或中科大的地址如果还是github.com说明环境变量没生效多半是export没有在正确的shell进程中执行手动source一次配置文件再试。第三步实际安装一个小软件比如wgetbrew install wget这一步会真实触发bottle下载最能检验整条链路。我在清华源下实测安装wget通常几十秒内完成。如果wget能装上说明brew仓库clone、API请求、bottle下载三条链路全部打通可以放心用了。4. 镜像配置与Homebrew基础操作4.1 让镜像配置持久生效装好Homebrew只是开始后面日常使用才是大头。这里有个很多人会踩的坑安装时注入的镜像环境变量只对当前shell进程生效。如果你只是临时export没有写入配置文件关掉终端再开配置就丢了brew update又会老老实实去连GitHub表现就是突然变卡甚至超时。脚本里已经帮你持久化到了.zprofile但我还是要多说一句macOS默认shell是zsh配置文件是.zprofile。如果你改用了bash那要写在.bash_profile或.bashrc里。验证配置是否生效的方式很简单开一个新终端窗口执行echo $HOMEBREW_BOTTLE_DOMAIN如果输出的是镜像地址说明持久化成功。没有输出的话手动把下面两行加到你的shell配置里export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles另外强调一遍Homebrew 4.x的配置是三件套除了BOTTLE_DOMAINAPI_DOMAIN也必须配。很多人漏了后者导致brew search、brew info这类走JSON API的命令还是卡顿。4.2 Homebrew日常高频操作速查镜像搭好后日常操作其实很简单。我把高频命令整理成了表格建议截图保存。操作命令说明搜索软件包brew search 关键词支持模糊匹配安装软件brew install 包名自动处理依赖最常用查看已装列表brew list列出所有通过brew安装的软件查看软件信息brew info 包名显示版本、路径、依赖情况更新仓库索引brew update拉取最新软件列表升级软件brew upgrade 包名先brew outdated看清单再升清理旧版本brew cleanup删除旧版本和缓存文件系统健康检查brew doctor报告潜在问题和修复建议我强烈建议新手培养两个习惯。第一个是安装前先brew search确认包名很多软件在brew里的名字跟你以为的不一样直接install会浪费时间。第二个是升级完跑一遍brew cleanupHomebrew下载的bottle缓存存在~/Library/Caches/Homebrew时间长了非常占磁盘尤其是经常装大型软件的人我清理的时候经常能释放出几个GB。4.3 Intel Mac装不上Homebrew的专项处理最近intel mac安装不了homebrew相关的话题热度不低。我实际测试下来Intel Mac并没有到装不了的地步而是有两个容易被忽略的门槛。第一个门槛是Xcode Command Line Tools版本匹配问题。Intel Mac如果系统版本停留在较旧的macOS而新版Homebrew要求更新的CLT安装脚本会报版本过旧。处理思路是更新系统或者单独重装CLT。重装CLT的路径是先删除/库/Developer/CommandLineTools目录然后重新执行xcode-select --install。第二个门槛是/usr/local目录的写权限。Intel Mac的Homebrew默认装到/usr/local而历史遗留问题经常让这个目录不属于当前用户安装时报permission denied。稳妥的处理方式是sudo chown -R $(whoami) /usr/local/Homebrew如果/usr/local/Homebrew还不存在先创建目录再改属主避免对整个/usr/local直接chown引发其他问题。另外网上有些旧教程会让你用sudo运行brew install这是非常危险的操作。sudo brew会让后续所有文件权限错乱排查起来很痛苦。正确思路永远是把目录权限拨给当前用户然后以普通用户身份运行brew命令。5. 常见报错与排查技巧实录5.1 高频报错速查表这几年我积累了不少用户反馈的报错案例90%都能归到下面几类。整理成速查表方便对照处理。报错信息出现阶段根因解决思路curl: (7) Failed to connect to raw.githubusercontent.com port 443下载install.shraw域名连接失败改用镜像转存的install.sh或提前下载到本地fatal: unable to access https://github.com/Homebrew/brew.git/git clone阶段仓库连接失败确认HOMEBREW_BREW_GIT_REMOTE已正确设置Error: Failure while executing; git clone ...git clone阶段网络中断或残留缓存清理/tmp下的安装缓存后重试Command Line Tools installation error系统依赖安装CLT安装被中断手动执行xcode-select --install等完整走完Permission denied rb_sysopenPATH配置后目录权限错误chown当前用户禁止sudo运行brewWarning: No remote origin foundbrew update仓库remote丢失cd到brew仓库目录手动添加remote这里最值得展开的是第一个。国内网络环境下raw.githubusercontent.com的连通性非常不稳定这也是为什么我在脚本里第一步不是直接跑install.sh而是优先从清华镜像拉取转存副本。你去看各种mac安装homebrew报错的求助帖卡住的截图十有八九都是curl连接raw超时。第一步绕开了这个域名后面的成功率会高一个量级。5.2 卸载残留与重装的一次性处理如果你反复安装失败系统里很可能积累了多个半截的残留文件。直接重装前最好把旧环境彻底清干净否则可能出现brew命令能找到但一运行就报错的诡异情况。官方提供了一键卸载脚本用法跟安装类似/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)如果卸载脚本拉不下来解决办法跟安装一样先下载到本地再执行。卸载脚本执行完成后还要手动检查几个残留目录。Apple Silicon机器是/opt/homebrewIntel机器是/usr/local/Homebrew、/usr/local/Caskroom、/usr/local/var等全局缓存目录是~/Library/Caches/Homebrew。我的建议是全部清干净再跑自动安装脚本。很多安装完成但brew命令找不到的问题都是旧目录里残留了一个坏掉的brew可执行文件把PATH指到了错误位置。干干净净装一次比花半天修补一个半残的安装高效得多。5.3 镜像源失效时的快速切换预案国内镜像整体稳定但偶尔也会抽风。比如某些源同步回源失败、或者证书更新出问题导致bottle 404。遇到这种情况我建议提前准备一套多源切换预案不要在出现问题的时候才临时查文档。# 在.zprofile中追加的备用源切换逻辑 _brew_mirror_fallback() { local brew_path$1 if ! $brew_path update --dry-run /dev/null 21; then export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api echo 已切换为中科大源 fi }这个函数是处理镜像失效时的手段不是万能药。日常使用中清华源出问题的概率很低真遇上了先检查网络再考虑切源。核心思路是别把所有鸡蛋放在一个篮子里手边至少熟悉两个源出问题时切换速度就是解决问题的速度。5.4 关于安装脚本的下载替代路径知乎、掘金、CSDN上有很多教程会在第一步教你用各种方式拿install.sh。除了清华镜像的转存路径国内还有个方式是用Gitee上的第三方转存。这些思路本质上都是绕开raw域名理解了这一点你就能举一反三。我个人实测下来的下载优先级是清华镜像转存地址第一这个地址稳定性和更新及时性都最好其次是提前在能正常连接的时候用curl拉取到本地最后才考虑从GitHub直连。注意安装脚本不要用太老的版本Homebrew更新节奏快老脚本可能不兼容当前的新版安装流程但核心思路是不变的。6. 再分享几条亲测有效的实操心得写到这里从零到精通的Homebrew国内镜像安装攻略基本结束了。最后分享几条我个人踩坑后觉得价值最高的心得。第一装Homebrew别在路径配置上走捷径。网上有些教程图省事让你直接echo一个PATH就完事看着简单但后续升级和依赖管理容易出现各种奇怪问题。官方推荐的eval $(/opt/homebrew/bin/brew shellenv)写法其实会把动态路径、man页路径、gem路径全部处理妥当效率反而更高。第二镜像配置装完别删。Homebrew更新频率很高每次brew update和软件安装都要跟远端仓库通信持久化配置能帮你省掉大量等待时间。我见过不少朋友装完把配置忘了几个月后突然发现brew变卡一查才知道环境变量丢了。第三遇到问题先看完整报错信息再动手别一上来就卸载重装。Homebrew的报错看着吓人但大部分都有明确的指向。先跑一遍brew doctor再对照本文的速查表超过八成问题都能解决。第四即使是同一台机器不同时间执行安装脚本网络状态不同结果也可能不同。如果你的安装失败了一次不要立刻重复跑同一个脚本先检查临时目录里的缓存是否残留再检查命令工具是否完整最后再重试。这套自动安装方案我在公司多台新Mac上跑过覆盖M1、M2和Intel没有一台因为安装问题返工。如果遇到本文没有覆盖到的报错拿报错信息去搜索通常也能找到对应镜像站的更新说明——针对国内网络环境的优化各家镜像站都在持续迭代保持关注就好。
Homebrew国内镜像安装全攻略：一键解决macOS装不上、卡在curl报错问题
1. Homebrew卡在第一步的问题根源1.1 Homebrew是什么为什么mac用户绕不开它Homebrew是macOS上最主流的包管理器地位相当于Linux世界的apt或yum。它解决的核心痛点是macOS不像Linux发行版那样自带一个成熟的软件包管理机制你装个nginx、redis、ffmpeg、wget如果纯手动搞要自己去官网找安装包、手动拖拽、逐个处理依赖库稍微复杂点的软件能把人折腾到怀疑人生。Homebrew把这一整套流程标准化了一条brew install就能把软件连同全部依赖一起装好卸载也干净利落。日常开发里高频用到的git、node、python、nginx、redis、docker-compose甚至一些GUI应用如google-chrome、visual-studio-code都能通过Homebrew统一管理。可以说对于一个mac开发者Homebrew的使用熟练度直接影响日常工作幸福感。网上大量相关热词也印证了这个工具的国民级使用率。但真实情况是很多人卡在了第一步——装不上。新拿到一台Mac、重装系统后、或者从Intel迁移到Apple Silicon之后很多人发现Homebrew就是装不上。报错信息五花八门有的卡在curl下载安装脚本有的卡在git clone仓库有的安装途中直接超时断开。1.2 官方安装脚本为什么总在关键步骤失败要理解怎么装先得知道Homebrew官方安装脚本到底做了什么。拆开看其实就四步第一步从GitHub的raw域名下载install.sh安装脚本第二步脚本内clone两个代码仓库brew本体和homebrew-core公式仓库第三步检查并安装Command Line Tools系统命令行工具第四步从GitHub的release地址下载预编译好的bottle二进制包。问题就出在第一步、第二步和第四步都依赖GitHub的网络链路。国内网络环境下raw.githubusercontent.com的连通性很不稳定git clone大仓库时也经常断流下载bottle时速度更是感人。我自己测试过直连状态下brew install一个300MB的软件下载速度可能只有几十KB每秒中途断开又得从头再来。所以整个行业里的常规解法就一个词换源。把brew仓库地址、homebrew-core仓库地址、bottle下载地址全部指向国内镜像节点。本文要做的就是把这套换源流程自动化一次脚本跑完不用手动设置一堆环境变量。这个方案我在Intel Mac和Apple Silicon的M1、M2机型上都验证过下面的内容会覆盖镜像选型、脚本细节、常见的mac安装homebrew报错处理、Intel Mac专项问题值得直接收藏照做。2. 镜像源选型与整体方案设计2.1 主流国内镜像源横向对比做Homebrew国内镜像本质上是替换三个东西brew.gitHomebrew本体代码仓库homebrew-core.git软件包公式仓库bottles预编译二进制包下载节点国内目前维护质量比较稳定的有清华TUNA、中科大USTC、阿里云三家。我把实际使用中的关键维度整理成了对比表。镜像源brew.githomebrew-core.gitbottles API实测速度稳定性清华TUNA支持支持支持快带宽充足常年在线同步及时中科大USTC支持支持支持快高峰期略有波动维护活跃文档完善阿里云支持支持支持较快偶尔有同步延迟这里要特别强调一个容易踩坑的版本差异Homebrew从4.0开始引入了JSON API机制公式索引默认不再完整clone整个homebrew-core仓库改为通过API动态拉取。这意味着安装配置时除了传统三个变量还要单独配置HOMEBREW_API_DOMAIN把API请求也指向国内镜像。很多老教程或者网上过时的内容只配置了BOTTLE_DOMAIN结果装完发现brew search、brew info这些命令依然卡顿就是因为API请求还在连GitHub。2.2 选型建议与组合方案我个人的推荐优先级是清华、中科大并列第一阿里云作为备选。清华和中科大的同步机制非常成熟遇到404或者回源失败的概率很低。另外有一个很多人忽略的细节——官方安装脚本本身在raw.githubusercontent.com上这一步是整个安装流程里最先卡住的地方。不少人的报错信息里curl连接raw域名直接失败连脚本都拉不下来。网络上的常规处理方式是用镜像站转存的install.sh副本或者提前把脚本下载到本地再执行。我在自动化脚本里会同时处理这个问题这算是我个人在实际操作中认为整个安装流程里性价比最高的一次改动能把成功率提升一大截。如果你所在网络环境对某一个镜像源连接不理想脚本里的三个源可以随时切换地址格式高度一致改起来也简单。我以下默认使用清华TUNA的主配置中科大和阿里云的地址会在代码注释里完整给出。3. 自动安装脚本实战从环境准备到一键完成3.1 安装前的三项环境检查在跑脚本之前强烈建议先花两分钟检查三件事能避免后面大量诡异的问题。第一确认Command Line Tools状态。Homebrew安装时会调用xcode-select检查命令行工具如果没有会自动触发安装。但这一步偶尔会卡住或者反复提示安装。我建议手动先执行一次xcode-select --install如果返回command line tools are already installed说明已经就绪。如果弹出了图形安装窗口等它完整走完再继续。这个过程下载量不小别中途关窗口。第二确认CPU架构。Apple Silicon和Intel Mac的Homebrew默认安装目录完全不同前者是/opt/homebrew后者是/usr/local。后续的PATH配置、目录权限都跟你是什么架构强相关。用一条命令确认uname -m输出arm64就是Apple Silicon输出x86_64就是Intel。第三检查是否有历史安装残留。如果之前安装失败过/opt/homebrew或者/usr/local下可能残留了残缺目录会严重干扰新安装。这个坑在第5章会专门讲这里先记住装之前确认目标目录是干净的。3.2 国内镜像自动安装脚本详解下面这个脚本就是整套方案的核心。它的流程是先用镜像源拉取install.sh安装脚本规避raw域名的不稳定问题然后注入清华镜像环境变量执行官方安装脚本最后自动写入PATH和持久化镜像配置。#!/bin/bash # Homebrew 国内镜像自动安装脚本 # 适用系统macOS 12 / Intel Apple Silicon # 默认源清华大学 TUNA可切换中科大、阿里云 # 1. 下载官方安装脚本优先从镜像站拉取 INSTALL_SCRIPT/tmp/install.sh echo 下载 Homebrew 安装脚本 curl -fsSL -o $INSTALL_SCRIPT \ https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.sh \ || curl -fsSL -o $INSTALL_SCRIPT \ https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh if [ ! -s $INSTALL_SCRIPT ]; then echo 安装脚本下载失败请检查网络后重试 exit 1 fi # 2. 注入国内镜像环境变量 echo 设置国内镜像源 export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api # 中科大源如需切换注释上方并取消注释下方 # 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 # 阿里云源如需切换注释上方并取消注释下方 # export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/brew.git # export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.aliyun.com/homebrew/homebrew-core.git # export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles # export HOMEBREW_API_DOMAINhttps://mirrors.aliyun.com/homebrew/homebrew-bottles/api # 3. 执行官方安装脚本 echo 开始执行安装请保持终端活跃 NONINTERACTIVE1 /bin/bash $INSTALL_SCRIPT # 4. 根据架构写入PATH配置 if [ $(uname -m) arm64 ]; then SHELL_RC$HOME/.zprofile BREW_PREFIX/opt/homebrew else SHELL_RC$HOME/.zprofile BREW_PREFIX/usr/local fi if ! grep -q $BREW_PREFIX/bin/brew $SHELL_RC 2/dev/null; then echo 写入brew环境变量到 $SHELL_RC echo eval \\$($BREW_PREFIX/bin/brew shellenv)\ $SHELL_RC fi echo 安装完成验证brew版本 export PATH$BREW_PREFIX/bin:$PATH brew --version # 5. 持久化镜像配置避免后续brew update回源GitHub if ! grep -q HOMEBREW_API_DOMAIN $SHELL_RC 2/dev/null; then echo 写入持久化镜像配置 cat $SHELL_RC EOF # Homebrew 国内镜像配置 export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles EOF fi echo 全部完成新开终端后执行 brew update 验证把脚本保存为install-homebrew-cn.sh然后执行chmod x install-homebrew-cn.sh /bin/bash install-homebrew-cn.sh脚本里有两个关键设计值得说明。第一NONINTERACTIVE1可以跳过官方脚本的交互式确认适合无人值守安装。第一次安装想观察过程的话可以去掉这个变量但自动化安装保留它更省心。第二第一行curl优先从清华镜像的install.sh拉取这步我在前面特别强调了raw域名不稳定是所有安装失败里占比最高的原因绕开它等于成功了一半。3.3 安装完成后的三步验证脚本跑完别急着高兴按下面三步确认真的没问题。第一步验证版本brew --version正常输出版本号说明brew本体已经可执行。第二步确认仓库remote指向镜像cd $(brew --repo) git remote -v正常应该显示清华或中科大的地址如果还是github.com说明环境变量没生效多半是export没有在正确的shell进程中执行手动source一次配置文件再试。第三步实际安装一个小软件比如wgetbrew install wget这一步会真实触发bottle下载最能检验整条链路。我在清华源下实测安装wget通常几十秒内完成。如果wget能装上说明brew仓库clone、API请求、bottle下载三条链路全部打通可以放心用了。4. 镜像配置与Homebrew基础操作4.1 让镜像配置持久生效装好Homebrew只是开始后面日常使用才是大头。这里有个很多人会踩的坑安装时注入的镜像环境变量只对当前shell进程生效。如果你只是临时export没有写入配置文件关掉终端再开配置就丢了brew update又会老老实实去连GitHub表现就是突然变卡甚至超时。脚本里已经帮你持久化到了.zprofile但我还是要多说一句macOS默认shell是zsh配置文件是.zprofile。如果你改用了bash那要写在.bash_profile或.bashrc里。验证配置是否生效的方式很简单开一个新终端窗口执行echo $HOMEBREW_BOTTLE_DOMAIN如果输出的是镜像地址说明持久化成功。没有输出的话手动把下面两行加到你的shell配置里export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles另外强调一遍Homebrew 4.x的配置是三件套除了BOTTLE_DOMAINAPI_DOMAIN也必须配。很多人漏了后者导致brew search、brew info这类走JSON API的命令还是卡顿。4.2 Homebrew日常高频操作速查镜像搭好后日常操作其实很简单。我把高频命令整理成了表格建议截图保存。操作命令说明搜索软件包brew search 关键词支持模糊匹配安装软件brew install 包名自动处理依赖最常用查看已装列表brew list列出所有通过brew安装的软件查看软件信息brew info 包名显示版本、路径、依赖情况更新仓库索引brew update拉取最新软件列表升级软件brew upgrade 包名先brew outdated看清单再升清理旧版本brew cleanup删除旧版本和缓存文件系统健康检查brew doctor报告潜在问题和修复建议我强烈建议新手培养两个习惯。第一个是安装前先brew search确认包名很多软件在brew里的名字跟你以为的不一样直接install会浪费时间。第二个是升级完跑一遍brew cleanupHomebrew下载的bottle缓存存在~/Library/Caches/Homebrew时间长了非常占磁盘尤其是经常装大型软件的人我清理的时候经常能释放出几个GB。4.3 Intel Mac装不上Homebrew的专项处理最近intel mac安装不了homebrew相关的话题热度不低。我实际测试下来Intel Mac并没有到装不了的地步而是有两个容易被忽略的门槛。第一个门槛是Xcode Command Line Tools版本匹配问题。Intel Mac如果系统版本停留在较旧的macOS而新版Homebrew要求更新的CLT安装脚本会报版本过旧。处理思路是更新系统或者单独重装CLT。重装CLT的路径是先删除/库/Developer/CommandLineTools目录然后重新执行xcode-select --install。第二个门槛是/usr/local目录的写权限。Intel Mac的Homebrew默认装到/usr/local而历史遗留问题经常让这个目录不属于当前用户安装时报permission denied。稳妥的处理方式是sudo chown -R $(whoami) /usr/local/Homebrew如果/usr/local/Homebrew还不存在先创建目录再改属主避免对整个/usr/local直接chown引发其他问题。另外网上有些旧教程会让你用sudo运行brew install这是非常危险的操作。sudo brew会让后续所有文件权限错乱排查起来很痛苦。正确思路永远是把目录权限拨给当前用户然后以普通用户身份运行brew命令。5. 常见报错与排查技巧实录5.1 高频报错速查表这几年我积累了不少用户反馈的报错案例90%都能归到下面几类。整理成速查表方便对照处理。报错信息出现阶段根因解决思路curl: (7) Failed to connect to raw.githubusercontent.com port 443下载install.shraw域名连接失败改用镜像转存的install.sh或提前下载到本地fatal: unable to access https://github.com/Homebrew/brew.git/git clone阶段仓库连接失败确认HOMEBREW_BREW_GIT_REMOTE已正确设置Error: Failure while executing; git clone ...git clone阶段网络中断或残留缓存清理/tmp下的安装缓存后重试Command Line Tools installation error系统依赖安装CLT安装被中断手动执行xcode-select --install等完整走完Permission denied rb_sysopenPATH配置后目录权限错误chown当前用户禁止sudo运行brewWarning: No remote origin foundbrew update仓库remote丢失cd到brew仓库目录手动添加remote这里最值得展开的是第一个。国内网络环境下raw.githubusercontent.com的连通性非常不稳定这也是为什么我在脚本里第一步不是直接跑install.sh而是优先从清华镜像拉取转存副本。你去看各种mac安装homebrew报错的求助帖卡住的截图十有八九都是curl连接raw超时。第一步绕开了这个域名后面的成功率会高一个量级。5.2 卸载残留与重装的一次性处理如果你反复安装失败系统里很可能积累了多个半截的残留文件。直接重装前最好把旧环境彻底清干净否则可能出现brew命令能找到但一运行就报错的诡异情况。官方提供了一键卸载脚本用法跟安装类似/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)如果卸载脚本拉不下来解决办法跟安装一样先下载到本地再执行。卸载脚本执行完成后还要手动检查几个残留目录。Apple Silicon机器是/opt/homebrewIntel机器是/usr/local/Homebrew、/usr/local/Caskroom、/usr/local/var等全局缓存目录是~/Library/Caches/Homebrew。我的建议是全部清干净再跑自动安装脚本。很多安装完成但brew命令找不到的问题都是旧目录里残留了一个坏掉的brew可执行文件把PATH指到了错误位置。干干净净装一次比花半天修补一个半残的安装高效得多。5.3 镜像源失效时的快速切换预案国内镜像整体稳定但偶尔也会抽风。比如某些源同步回源失败、或者证书更新出问题导致bottle 404。遇到这种情况我建议提前准备一套多源切换预案不要在出现问题的时候才临时查文档。# 在.zprofile中追加的备用源切换逻辑 _brew_mirror_fallback() { local brew_path$1 if ! $brew_path update --dry-run /dev/null 21; then export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api echo 已切换为中科大源 fi }这个函数是处理镜像失效时的手段不是万能药。日常使用中清华源出问题的概率很低真遇上了先检查网络再考虑切源。核心思路是别把所有鸡蛋放在一个篮子里手边至少熟悉两个源出问题时切换速度就是解决问题的速度。5.4 关于安装脚本的下载替代路径知乎、掘金、CSDN上有很多教程会在第一步教你用各种方式拿install.sh。除了清华镜像的转存路径国内还有个方式是用Gitee上的第三方转存。这些思路本质上都是绕开raw域名理解了这一点你就能举一反三。我个人实测下来的下载优先级是清华镜像转存地址第一这个地址稳定性和更新及时性都最好其次是提前在能正常连接的时候用curl拉取到本地最后才考虑从GitHub直连。注意安装脚本不要用太老的版本Homebrew更新节奏快老脚本可能不兼容当前的新版安装流程但核心思路是不变的。6. 再分享几条亲测有效的实操心得写到这里从零到精通的Homebrew国内镜像安装攻略基本结束了。最后分享几条我个人踩坑后觉得价值最高的心得。第一装Homebrew别在路径配置上走捷径。网上有些教程图省事让你直接echo一个PATH就完事看着简单但后续升级和依赖管理容易出现各种奇怪问题。官方推荐的eval $(/opt/homebrew/bin/brew shellenv)写法其实会把动态路径、man页路径、gem路径全部处理妥当效率反而更高。第二镜像配置装完别删。Homebrew更新频率很高每次brew update和软件安装都要跟远端仓库通信持久化配置能帮你省掉大量等待时间。我见过不少朋友装完把配置忘了几个月后突然发现brew变卡一查才知道环境变量丢了。第三遇到问题先看完整报错信息再动手别一上来就卸载重装。Homebrew的报错看着吓人但大部分都有明确的指向。先跑一遍brew doctor再对照本文的速查表超过八成问题都能解决。第四即使是同一台机器不同时间执行安装脚本网络状态不同结果也可能不同。如果你的安装失败了一次不要立刻重复跑同一个脚本先检查临时目录里的缓存是否残留再检查命令工具是否完整最后再重试。这套自动安装方案我在公司多台新Mac上跑过覆盖M1、M2和Intel没有一台因为安装问题返工。如果遇到本文没有覆盖到的报错拿报错信息去搜索通常也能找到对应镜像站的更新说明——针对国内网络环境的优化各家镜像站都在持续迭代保持关注就好。