尧图网站建设 
在 macOS 上做开发的人十有八九都会撞上 Homebrew。这玩意对程序员来说相当于 Ubuntu 上的 apt、CentOS 上的 yumwget、nginx、mysql、ffmpeg甚至现在很多人用的 ollama都能靠一条brew install搞定。但问题是Homebrew 默认把所有下载源都指向 GitHub国内网络环境下经常出现连接超时、SSL 握手失败、git clone 中断最后安装脚本黄字一屏报个curl: (28) Operation timed out很多人当场就懵了。我自己在 Mac 上装 Homebrew 的次数少说也有十多次踩过的坑比看过的教程还多。网上那些所谓“一键安装”的方法很多都是临时能跑、过几天又挂。真正靠谱的做法是把下载源换成国内镜像让安装脚本和后续更新都走国内节点。这篇就把“为什么失败”“装之前要查什么”“镜像怎么配”“出了问题怎么排查”全部讲透适合刚拿到 Mac 的新手也适合装失败之后想救回来的老用户。1. 为什么 Homebrew 在 Mac 上安装失败先把病因看清楚很多人在安装失败的第一反应是重试或者怀疑自己的电脑有问题。但根据我自己的经验Homebrew 装不上的原因其实高度集中逃不出下面这几类。先把症状看清楚后面才能真正对症下药。1.1 官方源全都在国外网络不稳定是最大变量Homebrew 的安装过程并不是一条命令从头到尾就完事它内部至少有三个下载环节。首先是安装脚本本身官方把它放在raw.githubusercontent.com上其次它要把Homebrew/brew仓库 clone 到本地最后它还会拉取homebrew-core这个核心公式仓库。这三个环节全部依赖 GitHub 的域名和 CDN而 GitHub 在海外的节点多、传输量大跨网络访问时经常出现连接被重置、SSL 握手超时、数据传输到一半断掉的情况。尤其brew仓库的历史提交记录非常庞大即使网络能通完整 clone 一次也可能要等几分钟甚至十几分钟。很多人看到进度条停在某个百分比不动以为死机了其实只是国外源传输太慢。国内镜像干的事情很简单把这三个环节的下载地址全部替换成清华、中科大这类国内服务器文件内容和官方完全一致但传输速度、稳定性完全不是一个级别。1.2 Xcode Command Line Tools 缺失新手最容易忽略Homebrew 不仅仅是个安装软件的工具它内部要调用系统的编译器、链接器和各种开发库。macOS 默认不会把这些工具装全需要你提前安装 Xcode Command Line Tools。如果你从来没有装过 Xcode也没有运行过任何需要编译器的软件Homebrew 安装脚本会在检查环境阶段直接报错提示找不到 Command Line Tools。这个坑特别隐蔽因为报错信息不会直接说“你没安装开发工具”而是混在其他错误里。比如你明明把网络问题解决了但安装脚本还是卡住或者执行到一半提示什么xcrun: error: invalid active developer path这时候就要回去检查命令行工具是不是装了。1.3 芯片架构、目录权限和历史残留Apple Silicon 芯片的 Mac 和 Intel 芯片的 MacHomebrew 的安装路径完全不同。Apple Silicon 默认装在/opt/homebrewIntel 默认装在/usr/local。如果你的 Mac 是 M 系列芯片但终端开了 Rosetta 模式或者你手动设置了奇怪的 PATH安装脚本会尝试往错误的位置写文件最后出现Cannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)这种报错很多人看到这里直接蒙圈。另外目录权限和历史残留也是一大来源。有的用户之前手动创建过/opt/homebrew目录但它属于 root当前用户没有写权限或者你以前装失败后残留了半截目录、符号链接、环境变量这些脏数据会让新安装脚本误以为你已经装过或者在覆盖时因为权限不足直接崩掉。所以“装前检查”真的不是浪费时间。2. 安装 Homebrew 前先把环境检查做完我有一个习惯不管在新 Mac 还是旧机器上装 Homebrew都先花两分钟做一轮检查确认架构、系统版本、开发工具、网络这几个核心变量没问题再跑安装命令。这一步能避免至少一半的安装失败。2.1 确认 macOS 版本和芯片架构先在终端里执行三条命令sw_vers uname -m sysctl -n machdep.cpu.brand_stringsw_vers会显示当前 macOS 的大版本比如 14.5 或者 15.0。uname -m输出arm64说明是 Apple Silicon输出x86_64说明是 Intel 芯片但也要注意如果是 Apple Silicon 却输出x86_64说明你当前的终端处于 Rosetta 2 模拟环境。sysctl -n machdep.cpu.brand_string能直接看到 CPU 型号判断是否在模拟环境下非常准。这三条命令看明白之后你就知道了后面该用/opt/homebrew还是/usr/local也知道为什么安装脚本会报 Rosetta 相关的错。顺便说一句如果系统版本太旧已经到了官方不再维护的范围后面安装脚本很可能会拒绝执行。遇到这种情况不要硬装新版 Homebrew优先考虑升级系统或者找对应的历史版本尝试。2.2 安装并验证 Xcode Command Line Tools如果之前没装过在终端输入下面的命令会弹出图形化安装窗口确认后会开始下载。xcode-select --install安装完成后可以校验一下路径和版本xcode-select -p xcodebuild -versionxcode-select -p应该输出/Library/Developer/CommandLineTools之类的路径xcodebuild -version能正常打印版本号就说明工具链没问题。很多人以为装过 Xcode 就等于装了命令行工具其实是从 App Store 装完整版 Xcode 之后还需要打开一次 Xcode或者手动执行上面这条命令命令行工具才会真正可用。还有个小细节如果系统之前装过命令行工具但版本偏老可能会出现“Command Line Tools are already installed”的提示这时候去“系统设置 - 软件更新”里把系统补丁打上一般就能解决。2.3 检查基础网络和同域名连通性网络检查不要只看“能不能打开网页”要看命令行工具能不能正常访问关键域名。先测一下镜像源是否连通curl -I https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git如果返回了 HTTP 状态码说明你能正常访问清华镜像。再看看有没有 DNS 解析问题curl -I https://github.com如果这条命令报Could not resolve host说明 DNS 解析异常可以临时换用公共 DNS 再试。生产环境的网络问题很怪有时候浏览器能打开但终端 curl 就是失败因为两者的 DNS、代理配置可能不一样。把这些前置问题排查完再开始安装心里会踏实很多。3. 国内镜像安装 Homebrew 的完整步骤下面分享两套我实测可行的方案。方案 A 是官方安装脚本配合环境变量适合大多数情况方案 B 是手动 git clone适合官方脚本死活下载不下来的时候。两者本质都是把 Homebrew 的下载源指到国内镜像。3.1 方案 A官方安装脚本加环境变量推荐优先用先明确一个概念Homebrew 官方安装脚本会读取环境变量HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_BOTTLE_DOMAIN如果你在运行脚本前把它们设置成国内镜像地址脚本就会自动绕开 GitHub。所以不需要去改脚本本身风险最小。第一步先安装 Xcode 命令行工具如果确认已经装过可以跳过xcode-select --install第二步在当前终端会话里设置环境变量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第三步下载并执行官方安装脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)执行过程中会看到脚本提示需要按回车确认并且可能会花几分钟更新仓库。这个阶段如果提示输入 sudo 密码就正常输入。安装完成后终端会提示你需要把 Homebrew 加到 PATH 里。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 -v brew doctor如果brew doctor输出 “Your system is ready to brew” 或者类似提示恭喜你装成功了。可以顺手拿brew install wget做个下载测试确认 bottle 镜像源也正常工作。这里有一个非常关键的注意事项如果你之前设置过其他 Homebrew 相关的环境变量比如HOMEBREW_...已经被写入~/.zshrc或者~/.zprofile新开终端后这些变量会自动生效临时 export 反而可能被它们覆盖。所以安装之前先echo $HOMEBREW_BREW_GIT_REMOTE看一眼如果有旧的镜像地址要么先清掉要么直接在用官方脚本之前把它们统一改掉。3.2 方案 B官方脚本下载不下来直接手动 git cloneraw.githubusercontent.com在国内的访问质量比较飘有时候 curl install.sh 这一步就失败了。这种情况不用死磕可以直接放弃安装脚本改用 git clone 从清华镜像把 Homebrew 仓库拉下来。Apple Silicon 芯片执行下面这一套sudo mkdir -p /opt/homebrew/Library/Taps/homebrew sudo chown -R $(whoami):$(id -gn) /opt/homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git /opt/homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git /opt/homebrew/Library/Taps/homebrew/homebrew-core git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git /opt/homebrew/Library/Taps/homebrew/homebrew-cask eval $(/opt/homebrew/bin/brew shellenv) brew doctorIntel 芯片执行这一套sudo mkdir -p /usr/local/Homebrew/Library/Taps/homebrew sudo chown -R $(whoami):$(id -gn) /usr/local/Homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git /usr/local/Homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask sudo mkdir -p /usr/local/bin sudo ln -sf /usr/local/Homebrew/bin/brew /usr/local/bin/brew eval $(/usr/local/Homebrew/bin/brew shellenv) brew doctor为什么还要手动 clonehomebrew-core和homebrew-cask因为官方安装脚本会默认拉齐这些仓库你手动安装时如果跳过第一次运行brew install就可能提示找不到核心公式或者自动去 GitHub 拉取等于又回到了老问题。虽然 Homebrew 4.x 开始默认走 JSON API很多情况下不需要本地 core 仓库但为了保险起见提前把这两个 tap 准备好后面不管用什么姿势安装软件都不会因为缺仓库而卡住。手动安装的缺点是安装脚本原本会帮你处理系统权限、PATH、目录优化这些细节现在你都要自己负责。所以执行完 clone 后千万记得跑brew doctor它会把权限问题、路径问题一条条列出来。我遇到过最典型的情况是sudo chown之后当前用户虽然能读目录但无权写入某些子目录brew doctor会直接报红按提示补 chown 就行。3.3 无网络安装脚本下载失败的保底方案除了手动 git clone还有一个保底办法是用社区维护的安装脚本。网上流传比较多、我之前也试用过的是 HomebrewCN 这个脚本它的地址在 Gitee 上好处是会引导你选择清华、中科大等镜像节点全程交互式安装比较适合不想手动敲一堆命令的情况。curl -fsSL -o /tmp/Homebrew.sh https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh这里我强烈建议你先别急着跑先看一眼脚本内容less /tmp/Homebrew.sh确认没有奇怪的敏感操作之后再执行bash /tmp/Homebrew.sh脚本会提示你选择镜像源输入对应的数字即可。用第三方脚本确实省事但本质上它也是在执行 curl、git clone、chown 这些操作运行前检查一遍是必要的习惯别拿一台存着重要数据的电脑当试验品。4. 镜像源怎么选常用源配置和切换方法镜像地址并不是越冷门越好反而越多人用、越正规的大镜像越稳定。国内社区使用最广的是清华 TUNA 和中科大 USTC两个都是教育网背景的大平台反代 GitHub 的同步频率高出问题也能很快找到文档。我自己主力用清华源备一个中科大源一个挂掉就切另一个。4.1 主流 Homebrew 国内镜像源对比我整理了一份自己常用的对照表方便你按需选择镜像源brew 仓库地址core 仓库地址bottle 下载域名清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.gitmirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.gitmirrors.tuna.tsinghua.edu.cn/homebrew-bottles中科大 USTCmirrors.ustc.edu.cn/brew.gitmirrors.ustc.edu.cn/homebrew-core.gitmirrors.ustc.edu.cn/homebrew-bottlesGitHub 官方github.com/Homebrew/brew.gitgithub.com/Homebrew/homebrew-core.gitghcr.io/v2/homebrew/core如果只是安装时用一下环境变量临时设置就够了。但如果你想长期稳定使用建议把镜像变量写进 shell 配置里让每次新开终端都自动生效。因为brew install不仅仅在安装阶段访问网络后续brew update、brew upgrade、下载 bottle 都会继续走这些地址。4.2 已安装 Homebrew 之后怎么一键切源有些用户不是从零安装而是原先已经装好了 Homebrew但更新很慢或者仓库 remote 地址还指向 GitHub。这种情况其实不需要重装只要把 git remote 地址改掉即可。先看看当前 brew 仓库的 remotegit -C $(brew --repo) remote -v如果输出的是github.com怎么换成清华源依次执行git -C $(brew --repo) remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git git -C $(brew --repo)/Library/Taps/homebrew/homebrew-core remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git git -C $(brew --repo)/Library/Taps/homebrew/homebrew-cask remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.gitbrew --repo在旧版本里用来显示 Homebrew 仓库路径如果你执行时发现这个命令已经不存在那就直接用具体路径。Apple Silicon 就是/opt/homebrewIntel 就是/usr/local/Homebrew把命令里的$(brew --repo)替换成实际路径即可。换完之后执行一次brew update如果速度明显改善说明切换成功。4.3 把镜像变量写进 shell 配置文件我建议把环境变量一次性写进~/.zshrc因为 macOS 默认 shell 是 zsh。用你习惯的文本编辑器打开这个文件在末尾加上export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles 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保存后执行source ~/.zshrc让配置立即生效。这里要特别说明一下HOMEBREW_API_DOMAIN这个变量Homebrew 4.x 以后会频繁从远程拉取公式的 JSON 元数据如果只设置了 bottle 域名而不设置 API 域名可能在brew install的时候还是会往国外地址请求导致安装过程莫名卡住。所以这两项最好成对配置。如果你用的是中科大源对应变量改成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需要注意切换 zshrc 里的镜像源之后之前手动 clone 的homebrew-coretap 如果还指向清华源也一并改掉否则会出现 git remote 对不上、brew update时产生大量合并冲突的情况。最省心的做法是确定一个主用源别在配置文件里混搭清华和中科大的地址。5. 安装失败常见问题与排查实录我在帮朋友和同事排查 Homebrew 问题的过程中发现有些报错反复出现。整理成一张清单你安装失败时可以对照着看。5.1 高频报错信息速查报错/现象可能原因解决办法curl: (28) Operation timed out after ...连接官方源超时改用国内镜像后重试Failed to connect to raw.githubusercontent.com port 443安装脚本下载源不通多试几次或使用方案 B 手动 clonefatal: unable to access https://github.com/Homebrew/brew/git clone 阶段访问 GitHub 失败设置HOMEBREW_BREW_GIT_REMOTE国内源Cannot install under Rosetta 2 in ARM default prefix终端处于 Rosetta 模拟环境打开原生终端确认uname -m输出 arm64/opt/homebrew is not writable目录属主不对执行sudo chown -R $(whoami):$(id -gn) /opt/homebrewCommand Line Tools for Xcode are not installed缺少命令行工具执行xcode-select --installbrew: command not foundPATH 环境变量没生效重新执行eval $(/opt/homebrew/bin/brew shellenv)这里单拎出 Rosetta 问题多说两句。很多用户是在老 Intel Mac 上用了迁移助理到 Apple Silicon 新机器然后桌面图标、终端 App 还保留着 Intel 版本打开之后其实是 x86_64 模拟环境。判断方法很简单终端里运行uname -m看到x86_64就说明终端本身跑在 Rosetta 下。解决方法是到“应用程序-实用工具”里确认终端 App 的“显示简介”里没有勾选“使用 Rosetta 打开”。5.2 官方安装脚本下载慢或失败怎么办curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh这一步卡住太常见了。我的经验是不要无脑反复重试先把脚本下载到本地用带超时和重试参数的 curl 命令curl -fsSL --connect-timeout 20 --retry 5 --retry-delay 2 -o /tmp/install.sh https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh下载完成后再执行bash /tmp/install.sh这样至少不用每次都从$(curl ...)这个子 shell 里重新建立连接。如果这个脚本已经下载成功但执行到 git clone 又卡住依然回到环境变量那一步确保当前 shell 里设置了HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE。安装脚本是按环境变量走还是按默认 walk取决于启动时有没有这些变量所以开新终端后别忘记重新 export。有时brew install单个软件时还会自动触发brew update导致整个终端窗口卡很久。我自己的习惯是安装明确的小软件时临时关闭自动更新HOMEBREW_NO_AUTO_UPDATE1 brew install wget这个变量按次生效不影响后续依赖更新能够避免很多无谓等待。5.3 卸载残留影响重装怎么清理如果你之前安装过或者安装失败到一半再重装的时候常常会遇到各种诡异冲突。最干净的方法是用官方卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)执行过程中脚本会问你是否删除/opt/homebrew下的所有文件确认后执行。卸载脚本跑完再手动检查几个可能有残留的位置。Apple Silicon 检查/opt/homebrewIntel 检查/usr/local/Homebrew、/usr/local/Cellar、/usr/local/Caskroom这些目录是否还存在有残留就手动删除。上面这些删除操作都是高危动作一定先确认目录名不要误删/usr/local里其他自己安装的内容。删除后还要检查~/.zprofile、~/.zshrc里的 Homebrew 环境变量把HOMEBREW_开头、brew shellenv相关的行清理干净否则重装完新终端还是会加载旧路径。清理干净之后重新按第 3 节的镜像安装方式走一遍成功率非常高。5.4 brew install 下载软件包时中断使用官方源安装单个软件时brew install mysql或brew install ollama这类命令经常会在下载二进制包阶段失败报错信息通常是curl相关或者download failed。这个阶段的问题基本都出在 bottle 下载源和 brew 本身关系不大。解决办法就是确认HOMEBREW_BOTTLE_DOMAIN已经指向国内镜像然后重新执行安装命令。有些软件包在镜像源里没有对应版本的 bottleHomebrew 会退回到源码编译这个过程耗时会比较长甚至因为依赖问题失败。遇到这种情况先brew update同步最新版本如果还是编译失败可以去对应公式的 GitHub 仓库看一下 issue多半是上游软件和当前系统版本的兼容问题不是你的配置有错。千万不要一看到编译报错就去重装 Homebrew这是很多新手最容易浪费时间的操作。6. 个人经验和长期使用小建议写到最后分享几条我自己的使用习惯不一定适用于所有人但至少能让你少走弯路。新机器到手之后不要一上来就到处找“一键脚本”先跑一遍xcode-select --install再把清华或中科大的镜像变量写进~/.zshrc最后用官方安装脚本装。这个流程最稳也最容易向同事解释。如果你已经装到一半失败优先用 clean uninstall 清理干净再重装而不是在脏目录上反复覆盖后者经常引入权限和 remote 冲突越改越乱。日常使用中brew update虽然不是每天要做但建议每周一次避免本地仓库和远端差异过大。切换镜像源之前一定要跑brew update让仓库同步否则可能遇到上游公式更新导致本地核心库过期。还有一点在 Apple Silicon 上安装的 Homebrew尽量给每个用户单独使用一个 prefix不要多用户共享/opt/homebrew否则权限问题会像滚雪球一样越滚越大。最后再说一个小技巧把brew install的动作拆小一次只装一个包不要一条命令后面跟十几个软件名。这样做的好处是一旦某个包下载失败你能立刻定位到是哪一个不会一大片输出刷过去之后什么都看不清。Homebrew 本身是个好工具解决了 macOS 上软件安装的碎片化问题只要把它初装时的网络问题处理干净后面用起来会相当顺畅。 macOS安装Homebrew失败？国内镜像配置与避坑指南
在 macOS 上做开发的人十有八九都会撞上 Homebrew。这玩意对程序员来说相当于 Ubuntu 上的 apt、CentOS 上的 yumwget、nginx、mysql、ffmpeg甚至现在很多人用的 ollama都能靠一条brew install搞定。但问题是Homebrew 默认把所有下载源都指向 GitHub国内网络环境下经常出现连接超时、SSL 握手失败、git clone 中断最后安装脚本黄字一屏报个curl: (28) Operation timed out很多人当场就懵了。我自己在 Mac 上装 Homebrew 的次数少说也有十多次踩过的坑比看过的教程还多。网上那些所谓“一键安装”的方法很多都是临时能跑、过几天又挂。真正靠谱的做法是把下载源换成国内镜像让安装脚本和后续更新都走国内节点。这篇就把“为什么失败”“装之前要查什么”“镜像怎么配”“出了问题怎么排查”全部讲透适合刚拿到 Mac 的新手也适合装失败之后想救回来的老用户。1. 为什么 Homebrew 在 Mac 上安装失败先把病因看清楚很多人在安装失败的第一反应是重试或者怀疑自己的电脑有问题。但根据我自己的经验Homebrew 装不上的原因其实高度集中逃不出下面这几类。先把症状看清楚后面才能真正对症下药。1.1 官方源全都在国外网络不稳定是最大变量Homebrew 的安装过程并不是一条命令从头到尾就完事它内部至少有三个下载环节。首先是安装脚本本身官方把它放在raw.githubusercontent.com上其次它要把Homebrew/brew仓库 clone 到本地最后它还会拉取homebrew-core这个核心公式仓库。这三个环节全部依赖 GitHub 的域名和 CDN而 GitHub 在海外的节点多、传输量大跨网络访问时经常出现连接被重置、SSL 握手超时、数据传输到一半断掉的情况。尤其brew仓库的历史提交记录非常庞大即使网络能通完整 clone 一次也可能要等几分钟甚至十几分钟。很多人看到进度条停在某个百分比不动以为死机了其实只是国外源传输太慢。国内镜像干的事情很简单把这三个环节的下载地址全部替换成清华、中科大这类国内服务器文件内容和官方完全一致但传输速度、稳定性完全不是一个级别。1.2 Xcode Command Line Tools 缺失新手最容易忽略Homebrew 不仅仅是个安装软件的工具它内部要调用系统的编译器、链接器和各种开发库。macOS 默认不会把这些工具装全需要你提前安装 Xcode Command Line Tools。如果你从来没有装过 Xcode也没有运行过任何需要编译器的软件Homebrew 安装脚本会在检查环境阶段直接报错提示找不到 Command Line Tools。这个坑特别隐蔽因为报错信息不会直接说“你没安装开发工具”而是混在其他错误里。比如你明明把网络问题解决了但安装脚本还是卡住或者执行到一半提示什么xcrun: error: invalid active developer path这时候就要回去检查命令行工具是不是装了。1.3 芯片架构、目录权限和历史残留Apple Silicon 芯片的 Mac 和 Intel 芯片的 MacHomebrew 的安装路径完全不同。Apple Silicon 默认装在/opt/homebrewIntel 默认装在/usr/local。如果你的 Mac 是 M 系列芯片但终端开了 Rosetta 模式或者你手动设置了奇怪的 PATH安装脚本会尝试往错误的位置写文件最后出现Cannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)这种报错很多人看到这里直接蒙圈。另外目录权限和历史残留也是一大来源。有的用户之前手动创建过/opt/homebrew目录但它属于 root当前用户没有写权限或者你以前装失败后残留了半截目录、符号链接、环境变量这些脏数据会让新安装脚本误以为你已经装过或者在覆盖时因为权限不足直接崩掉。所以“装前检查”真的不是浪费时间。2. 安装 Homebrew 前先把环境检查做完我有一个习惯不管在新 Mac 还是旧机器上装 Homebrew都先花两分钟做一轮检查确认架构、系统版本、开发工具、网络这几个核心变量没问题再跑安装命令。这一步能避免至少一半的安装失败。2.1 确认 macOS 版本和芯片架构先在终端里执行三条命令sw_vers uname -m sysctl -n machdep.cpu.brand_stringsw_vers会显示当前 macOS 的大版本比如 14.5 或者 15.0。uname -m输出arm64说明是 Apple Silicon输出x86_64说明是 Intel 芯片但也要注意如果是 Apple Silicon 却输出x86_64说明你当前的终端处于 Rosetta 2 模拟环境。sysctl -n machdep.cpu.brand_string能直接看到 CPU 型号判断是否在模拟环境下非常准。这三条命令看明白之后你就知道了后面该用/opt/homebrew还是/usr/local也知道为什么安装脚本会报 Rosetta 相关的错。顺便说一句如果系统版本太旧已经到了官方不再维护的范围后面安装脚本很可能会拒绝执行。遇到这种情况不要硬装新版 Homebrew优先考虑升级系统或者找对应的历史版本尝试。2.2 安装并验证 Xcode Command Line Tools如果之前没装过在终端输入下面的命令会弹出图形化安装窗口确认后会开始下载。xcode-select --install安装完成后可以校验一下路径和版本xcode-select -p xcodebuild -versionxcode-select -p应该输出/Library/Developer/CommandLineTools之类的路径xcodebuild -version能正常打印版本号就说明工具链没问题。很多人以为装过 Xcode 就等于装了命令行工具其实是从 App Store 装完整版 Xcode 之后还需要打开一次 Xcode或者手动执行上面这条命令命令行工具才会真正可用。还有个小细节如果系统之前装过命令行工具但版本偏老可能会出现“Command Line Tools are already installed”的提示这时候去“系统设置 - 软件更新”里把系统补丁打上一般就能解决。2.3 检查基础网络和同域名连通性网络检查不要只看“能不能打开网页”要看命令行工具能不能正常访问关键域名。先测一下镜像源是否连通curl -I https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git如果返回了 HTTP 状态码说明你能正常访问清华镜像。再看看有没有 DNS 解析问题curl -I https://github.com如果这条命令报Could not resolve host说明 DNS 解析异常可以临时换用公共 DNS 再试。生产环境的网络问题很怪有时候浏览器能打开但终端 curl 就是失败因为两者的 DNS、代理配置可能不一样。把这些前置问题排查完再开始安装心里会踏实很多。3. 国内镜像安装 Homebrew 的完整步骤下面分享两套我实测可行的方案。方案 A 是官方安装脚本配合环境变量适合大多数情况方案 B 是手动 git clone适合官方脚本死活下载不下来的时候。两者本质都是把 Homebrew 的下载源指到国内镜像。3.1 方案 A官方安装脚本加环境变量推荐优先用先明确一个概念Homebrew 官方安装脚本会读取环境变量HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_BOTTLE_DOMAIN如果你在运行脚本前把它们设置成国内镜像地址脚本就会自动绕开 GitHub。所以不需要去改脚本本身风险最小。第一步先安装 Xcode 命令行工具如果确认已经装过可以跳过xcode-select --install第二步在当前终端会话里设置环境变量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第三步下载并执行官方安装脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)执行过程中会看到脚本提示需要按回车确认并且可能会花几分钟更新仓库。这个阶段如果提示输入 sudo 密码就正常输入。安装完成后终端会提示你需要把 Homebrew 加到 PATH 里。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 -v brew doctor如果brew doctor输出 “Your system is ready to brew” 或者类似提示恭喜你装成功了。可以顺手拿brew install wget做个下载测试确认 bottle 镜像源也正常工作。这里有一个非常关键的注意事项如果你之前设置过其他 Homebrew 相关的环境变量比如HOMEBREW_...已经被写入~/.zshrc或者~/.zprofile新开终端后这些变量会自动生效临时 export 反而可能被它们覆盖。所以安装之前先echo $HOMEBREW_BREW_GIT_REMOTE看一眼如果有旧的镜像地址要么先清掉要么直接在用官方脚本之前把它们统一改掉。3.2 方案 B官方脚本下载不下来直接手动 git cloneraw.githubusercontent.com在国内的访问质量比较飘有时候 curl install.sh 这一步就失败了。这种情况不用死磕可以直接放弃安装脚本改用 git clone 从清华镜像把 Homebrew 仓库拉下来。Apple Silicon 芯片执行下面这一套sudo mkdir -p /opt/homebrew/Library/Taps/homebrew sudo chown -R $(whoami):$(id -gn) /opt/homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git /opt/homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git /opt/homebrew/Library/Taps/homebrew/homebrew-core git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git /opt/homebrew/Library/Taps/homebrew/homebrew-cask eval $(/opt/homebrew/bin/brew shellenv) brew doctorIntel 芯片执行这一套sudo mkdir -p /usr/local/Homebrew/Library/Taps/homebrew sudo chown -R $(whoami):$(id -gn) /usr/local/Homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git /usr/local/Homebrew git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask sudo mkdir -p /usr/local/bin sudo ln -sf /usr/local/Homebrew/bin/brew /usr/local/bin/brew eval $(/usr/local/Homebrew/bin/brew shellenv) brew doctor为什么还要手动 clonehomebrew-core和homebrew-cask因为官方安装脚本会默认拉齐这些仓库你手动安装时如果跳过第一次运行brew install就可能提示找不到核心公式或者自动去 GitHub 拉取等于又回到了老问题。虽然 Homebrew 4.x 开始默认走 JSON API很多情况下不需要本地 core 仓库但为了保险起见提前把这两个 tap 准备好后面不管用什么姿势安装软件都不会因为缺仓库而卡住。手动安装的缺点是安装脚本原本会帮你处理系统权限、PATH、目录优化这些细节现在你都要自己负责。所以执行完 clone 后千万记得跑brew doctor它会把权限问题、路径问题一条条列出来。我遇到过最典型的情况是sudo chown之后当前用户虽然能读目录但无权写入某些子目录brew doctor会直接报红按提示补 chown 就行。3.3 无网络安装脚本下载失败的保底方案除了手动 git clone还有一个保底办法是用社区维护的安装脚本。网上流传比较多、我之前也试用过的是 HomebrewCN 这个脚本它的地址在 Gitee 上好处是会引导你选择清华、中科大等镜像节点全程交互式安装比较适合不想手动敲一堆命令的情况。curl -fsSL -o /tmp/Homebrew.sh https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh这里我强烈建议你先别急着跑先看一眼脚本内容less /tmp/Homebrew.sh确认没有奇怪的敏感操作之后再执行bash /tmp/Homebrew.sh脚本会提示你选择镜像源输入对应的数字即可。用第三方脚本确实省事但本质上它也是在执行 curl、git clone、chown 这些操作运行前检查一遍是必要的习惯别拿一台存着重要数据的电脑当试验品。4. 镜像源怎么选常用源配置和切换方法镜像地址并不是越冷门越好反而越多人用、越正规的大镜像越稳定。国内社区使用最广的是清华 TUNA 和中科大 USTC两个都是教育网背景的大平台反代 GitHub 的同步频率高出问题也能很快找到文档。我自己主力用清华源备一个中科大源一个挂掉就切另一个。4.1 主流 Homebrew 国内镜像源对比我整理了一份自己常用的对照表方便你按需选择镜像源brew 仓库地址core 仓库地址bottle 下载域名清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.gitmirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.gitmirrors.tuna.tsinghua.edu.cn/homebrew-bottles中科大 USTCmirrors.ustc.edu.cn/brew.gitmirrors.ustc.edu.cn/homebrew-core.gitmirrors.ustc.edu.cn/homebrew-bottlesGitHub 官方github.com/Homebrew/brew.gitgithub.com/Homebrew/homebrew-core.gitghcr.io/v2/homebrew/core如果只是安装时用一下环境变量临时设置就够了。但如果你想长期稳定使用建议把镜像变量写进 shell 配置里让每次新开终端都自动生效。因为brew install不仅仅在安装阶段访问网络后续brew update、brew upgrade、下载 bottle 都会继续走这些地址。4.2 已安装 Homebrew 之后怎么一键切源有些用户不是从零安装而是原先已经装好了 Homebrew但更新很慢或者仓库 remote 地址还指向 GitHub。这种情况其实不需要重装只要把 git remote 地址改掉即可。先看看当前 brew 仓库的 remotegit -C $(brew --repo) remote -v如果输出的是github.com怎么换成清华源依次执行git -C $(brew --repo) remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git git -C $(brew --repo)/Library/Taps/homebrew/homebrew-core remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git git -C $(brew --repo)/Library/Taps/homebrew/homebrew-cask remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.gitbrew --repo在旧版本里用来显示 Homebrew 仓库路径如果你执行时发现这个命令已经不存在那就直接用具体路径。Apple Silicon 就是/opt/homebrewIntel 就是/usr/local/Homebrew把命令里的$(brew --repo)替换成实际路径即可。换完之后执行一次brew update如果速度明显改善说明切换成功。4.3 把镜像变量写进 shell 配置文件我建议把环境变量一次性写进~/.zshrc因为 macOS 默认 shell 是 zsh。用你习惯的文本编辑器打开这个文件在末尾加上export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles 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保存后执行source ~/.zshrc让配置立即生效。这里要特别说明一下HOMEBREW_API_DOMAIN这个变量Homebrew 4.x 以后会频繁从远程拉取公式的 JSON 元数据如果只设置了 bottle 域名而不设置 API 域名可能在brew install的时候还是会往国外地址请求导致安装过程莫名卡住。所以这两项最好成对配置。如果你用的是中科大源对应变量改成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需要注意切换 zshrc 里的镜像源之后之前手动 clone 的homebrew-coretap 如果还指向清华源也一并改掉否则会出现 git remote 对不上、brew update时产生大量合并冲突的情况。最省心的做法是确定一个主用源别在配置文件里混搭清华和中科大的地址。5. 安装失败常见问题与排查实录我在帮朋友和同事排查 Homebrew 问题的过程中发现有些报错反复出现。整理成一张清单你安装失败时可以对照着看。5.1 高频报错信息速查报错/现象可能原因解决办法curl: (28) Operation timed out after ...连接官方源超时改用国内镜像后重试Failed to connect to raw.githubusercontent.com port 443安装脚本下载源不通多试几次或使用方案 B 手动 clonefatal: unable to access https://github.com/Homebrew/brew/git clone 阶段访问 GitHub 失败设置HOMEBREW_BREW_GIT_REMOTE国内源Cannot install under Rosetta 2 in ARM default prefix终端处于 Rosetta 模拟环境打开原生终端确认uname -m输出 arm64/opt/homebrew is not writable目录属主不对执行sudo chown -R $(whoami):$(id -gn) /opt/homebrewCommand Line Tools for Xcode are not installed缺少命令行工具执行xcode-select --installbrew: command not foundPATH 环境变量没生效重新执行eval $(/opt/homebrew/bin/brew shellenv)这里单拎出 Rosetta 问题多说两句。很多用户是在老 Intel Mac 上用了迁移助理到 Apple Silicon 新机器然后桌面图标、终端 App 还保留着 Intel 版本打开之后其实是 x86_64 模拟环境。判断方法很简单终端里运行uname -m看到x86_64就说明终端本身跑在 Rosetta 下。解决方法是到“应用程序-实用工具”里确认终端 App 的“显示简介”里没有勾选“使用 Rosetta 打开”。5.2 官方安装脚本下载慢或失败怎么办curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh这一步卡住太常见了。我的经验是不要无脑反复重试先把脚本下载到本地用带超时和重试参数的 curl 命令curl -fsSL --connect-timeout 20 --retry 5 --retry-delay 2 -o /tmp/install.sh https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh下载完成后再执行bash /tmp/install.sh这样至少不用每次都从$(curl ...)这个子 shell 里重新建立连接。如果这个脚本已经下载成功但执行到 git clone 又卡住依然回到环境变量那一步确保当前 shell 里设置了HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE。安装脚本是按环境变量走还是按默认 walk取决于启动时有没有这些变量所以开新终端后别忘记重新 export。有时brew install单个软件时还会自动触发brew update导致整个终端窗口卡很久。我自己的习惯是安装明确的小软件时临时关闭自动更新HOMEBREW_NO_AUTO_UPDATE1 brew install wget这个变量按次生效不影响后续依赖更新能够避免很多无谓等待。5.3 卸载残留影响重装怎么清理如果你之前安装过或者安装失败到一半再重装的时候常常会遇到各种诡异冲突。最干净的方法是用官方卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)执行过程中脚本会问你是否删除/opt/homebrew下的所有文件确认后执行。卸载脚本跑完再手动检查几个可能有残留的位置。Apple Silicon 检查/opt/homebrewIntel 检查/usr/local/Homebrew、/usr/local/Cellar、/usr/local/Caskroom这些目录是否还存在有残留就手动删除。上面这些删除操作都是高危动作一定先确认目录名不要误删/usr/local里其他自己安装的内容。删除后还要检查~/.zprofile、~/.zshrc里的 Homebrew 环境变量把HOMEBREW_开头、brew shellenv相关的行清理干净否则重装完新终端还是会加载旧路径。清理干净之后重新按第 3 节的镜像安装方式走一遍成功率非常高。5.4 brew install 下载软件包时中断使用官方源安装单个软件时brew install mysql或brew install ollama这类命令经常会在下载二进制包阶段失败报错信息通常是curl相关或者download failed。这个阶段的问题基本都出在 bottle 下载源和 brew 本身关系不大。解决办法就是确认HOMEBREW_BOTTLE_DOMAIN已经指向国内镜像然后重新执行安装命令。有些软件包在镜像源里没有对应版本的 bottleHomebrew 会退回到源码编译这个过程耗时会比较长甚至因为依赖问题失败。遇到这种情况先brew update同步最新版本如果还是编译失败可以去对应公式的 GitHub 仓库看一下 issue多半是上游软件和当前系统版本的兼容问题不是你的配置有错。千万不要一看到编译报错就去重装 Homebrew这是很多新手最容易浪费时间的操作。6. 个人经验和长期使用小建议写到最后分享几条我自己的使用习惯不一定适用于所有人但至少能让你少走弯路。新机器到手之后不要一上来就到处找“一键脚本”先跑一遍xcode-select --install再把清华或中科大的镜像变量写进~/.zshrc最后用官方安装脚本装。这个流程最稳也最容易向同事解释。如果你已经装到一半失败优先用 clean uninstall 清理干净再重装而不是在脏目录上反复覆盖后者经常引入权限和 remote 冲突越改越乱。日常使用中brew update虽然不是每天要做但建议每周一次避免本地仓库和远端差异过大。切换镜像源之前一定要跑brew update让仓库同步否则可能遇到上游公式更新导致本地核心库过期。还有一点在 Apple Silicon 上安装的 Homebrew尽量给每个用户单独使用一个 prefix不要多用户共享/opt/homebrew否则权限问题会像滚雪球一样越滚越大。最后再说一个小技巧把brew install的动作拆小一次只装一个包不要一条命令后面跟十几个软件名。这样做的好处是一旦某个包下载失败你能立刻定位到是哪一个不会一大片输出刷过去之后什么都看不清。Homebrew 本身是个好工具解决了 macOS 上软件安装的碎片化问题只要把它初装时的网络问题处理干净后面用起来会相当顺畅。