简介这份资源是面向国内 macOS 用户的 Homebrew 国内安装脚本合集主要解决官方源下载缓慢甚至无法访问的问题。包内共 12 个文件以 5 个 sh 脚本为主涵盖安装、卸载、Git 环境准备等环节另有 3 个 md 说明文档、2 张运行过程截图以及 LICENSE 等辅助文件压缩包约 458KB体积轻便、开箱即用。脚本会自动将 Homebrew 配置切换至国内镜像源并完成依赖下载与安装流程安装后可用 brew doctor 验证配置是否正常。目前已有 1206 人学习下载适合需要快速搭建命令行开发环境、又不想被网络问题困扰的开发者与运维人员参考使用。1. 从一次brew install卡住说起这套脚本到底替你干了什么如果你在 macOS 上敲下brew install wget然后盯着终端十几分钟没动静最后蹦出一串Failed to connect to raw.githubusercontent.com port 443那你不是一个人。Homebrew 本身没问题问题出在它默认把 Git 仓库、 bottle 二进制包、API 元数据全指向国外地址国内直连基本靠运气。HomebrewCN 这套脚本解决的就是这个它把 Homebrew 的安装流程和后续拉取源整体切到国内镜像让你从「装不上」变成「能装上、能更新、能正常用」。这个资源包HomebrewCN-master里不只是一个install.sh还带了HomebrewUninstall.sh、installGIT.sh、test.sh、国外版本.sh和一份error.md。换句话说它把安装、卸载、Git 依赖补齐、出错排查这几件事都覆盖了。适合两类人一是刚拿到 Mac、命令行还没配明白的新手照着跑就能把 brew 立起来二是被官方源反复折磨、想换镜像又不想手动改一堆配置的老手可以直接拆脚本看它改了哪些文件、写了哪些环境变量。我拆这个包的时候最直观的感受是它没有魔法核心就是「换源 补依赖 写 shell 配置」。但恰恰是这几步手动做容易漏、容易写错路径脚本把它固化成可重复执行的流程这才是价值所在。2. 拆开 HomebrewCN-master文件清单与镜像替换逻辑2.1 压缩包里每个文件对应哪一步先把包解开别急着跑。用ls -la看一眼目录你会发现文件不多但分工明确。下面这张表是我按实际用途整理的不是官方说明是我自己跑过之后对号入座的结果。文件名作用什么时候用Homebrew.sh主安装脚本负责换源并安装 brew首次安装国外版本.sh走官方源的安装流程想对比或镜像出问题时回退installGIT.sh检查并安装 GitXcode CLT 或独立包系统没有 git 命令时HomebrewUninstall.sh卸载 brew 及残留目录装坏了、想重来test.sh安装后自检验证 brew 命令可用装完验证error.md常见报错记录卡住时先翻它这里有个细节值得说installGIT.sh单独存在说明作者很清楚国内新机器经常连git都没有而 Homebrew 的安装本身依赖 Git 去 clone 仓库。所以正确顺序不是上来就跑主脚本而是先确认 Git 在不在。2.2 镜像替换到底改了哪些东西Homebrew 的「源」其实分好几层很多人以为改一个HOMEBREW_BREW_GIT_REMOTE就完事结果brew update还是慢。常见做法是同时处理这几类地址brew 仓库本身HOMEBREW_BREW_GIT_REMOTE指向 brew 主仓库的镜像。core tapHOMEBREW_CORE_GIT_REMOTE公式定义所在仓库。bottle 二进制包HOMEBREW_BOTTLE_DOMAIN这是下载预编译包的地方不改它装软件照样慢。API 域名新版 brew 用HOMEBREW_API_DOMAIN拉元数据不换会卡在Updating Homebrew。脚本干的事就是把这些变量写进你的 shell 配置文件~/.bash_profile或~/.zshrc再执行安装。你可以先手动看一眼当前配置确认脚本会往哪写# 查看当前 shell决定改哪个配置文件 echo $SHELL # 如果输出 /bin/zsh配置文件通常是 ~/.zshrc # 如果输出 /bin/bash通常是 ~/.bash_profile # 看看现在有没有已经存在的 brew 相关环境变量 env | grep HOMEBREW逻辑说明echo $SHELL决定后续环境变量写进哪个文件写错文件会导致「明明配了却不生效」这种玄学问题。env | grep HOMEBREW是排查前置污染如果你之前手动改过一半脚本再追加可能产生重复或冲突。参数上没什么可调的这一步纯粹是摸清现状。2.3 为什么用脚本而不是手动一条条敲手动换源不是不行但有几个坑一是变量名容易记混HOMEBREW_BOTTLE_DOMAIN和HOMEBREW_API_DOMAIN少写一个就前功尽弃二是不同 macOS 版本默认 shell 不同写错文件白干三是安装过程中如果中断残留目录会让下次安装报already exists。脚本把这些顺序和判断固定下来本质是把你从「记命令」里解放出来。这也是我愿意留一份在本地的原因——重装系统时不用再翻笔记。3. 照着跑一遍从解压到brew doctor通过3.1 前置检查Git、网络与权限在跑主脚本之前先做三件事能省掉后面一大半报错。第一确认 Git 可用第二确认当前用户对/opt/homebrewApple Silicon或/usr/localIntel有写权限第三确认终端能正常访问镜像地址。# 1. 检查 git 是否存在 git --version # 没有输出或报 command not found就先跑 installGIT.sh # 2. 判断芯片架构决定 brew 安装前缀 uname -m # arm64 - /opt/homebrew # x86_64 - /usr/local # 3. 给脚本执行权限在解压后的目录里 chmod x Homebrew.sh installGIT.sh test.sh HomebrewUninstall.sh逻辑说明git --version是最容易被忽略的前置很多「安装脚本跑一半失败」的根因就是没有 Git。uname -m决定 brew 装到哪个前缀目录Apple Silicon 和 Intel 的路径不同后面排查权限问题时要对得上。chmod x是必须的从压缩包解出来的脚本默认没有执行位直接./Homebrew.sh会报Permission denied。提示如果你之前装过 brew 但没装成功先别急着跑主脚本用HomebrewUninstall.sh清一遍否则残留目录会让新安装直接失败。3.2 执行主脚本与交互选择前置没问题后进入解压目录执行主脚本。它通常会让你选一个镜像源编号不同编号对应不同国内镜像选一个延迟低的即可。# 进入解压后的目录路径按你实际解压位置改 cd ~/Downloads/HomebrewCN-master # 执行主安装脚本 ./Homebrew.sh执行后终端会打印一段菜单让你输入数字选择镜像源。这一步没有标准答案选一个你网络环境下响应快的就行选完脚本会自动写入环境变量、clone brew 仓库、执行安装、最后提示你把某行配置加到 shell 文件。逻辑上它是「先配环境变量再安装」这样安装过程中拉取就已经走镜像了。参数方面你唯一能控制的就是镜像编号其余交给脚本。3.3 让环境变量生效并验证脚本跑完后新写入的环境变量不会自动在当前终端生效必须重新加载配置文件或者干脆开一个新终端窗口。# 如果用的是 zsh source ~/.zshrc # 如果用的是 bash source ~/.bash_profile # 验证 brew 命令是否可用 brew --version # 跑一次官方自检 brew doctor逻辑说明source是让当前会话重新读取配置文件不执行这步你会以为「装了但命令找不到」。brew --version能输出版本号说明可执行文件已进 PATH。brew doctor是官方自检它会告诉你哪些配置有问题比如残留文件、权限异常、PATH 顺序不对。注意brew doctor输出Your system is ready to brew才算干净如果它列了一堆 warning先按提示处理别急着装软件。3.4 装一个包验证镜像是否真的生效光看版本号不够得实际装一个包观察下载速度才能确认 bottle 源也换对了。# 装一个小工具测试下载速度 brew install wget # 看 brew 当前使用的各项源 brew config逻辑说明brew install wget会触发 bottle 下载如果几秒内完成说明HOMEBREW_BOTTLE_DOMAIN生效了如果还是慢说明只换了 Git 源没换 bottle 源。brew config会打印HOMEBREW_BOTTLE_DOMAIN、HOMEBREW_API_DOMAIN等实际值这是验证换源是否彻底的最直接手段比猜靠谱。4. 避坑与排查那些让我重装三次的报错4.1 报错Failed to connect to raw.githubusercontent.com现象脚本跑到 clone 阶段卡住最后报连接超时。原因环境变量没生效就执行了安装或者镜像编号选了一个当前网络不通的源。解决先source配置文件确认变量已写入再env | grep HOMEBREW看值对不对不对就换一个镜像编号重跑别硬等。4.2 报错Permission denied或not writable现象安装到一半提示目录不可写。原因之前用sudo装过 brew导致/opt/homebrew或/usr/local归属 root当前用户没权限。解决先跑HomebrewUninstall.sh清理再确认目录归属必要时用sudo chown -R $(whoami)把目录还给自己然后重新安装。血泪经验是装 brew 全程不要用sudo。4.3brew命令找不到现象装完了敲brew提示command not found。原因环境变量写进了错误的配置文件比如你是 zsh 却写进了~/.bash_profile。解决echo $SHELL确认 shell把脚本提示的那行eval或export PATH加到正确的文件里再source一次。4.4 安装后brew update依然很慢现象装软件快了但brew update卡在Updating Homebrew。原因只换了 bottle 源没换 API 域名或 core tap。解决brew config逐项检查把缺失的HOMEBREW_API_DOMAIN、HOMEBREW_CORE_GIT_REMOTE补进配置文件重新source。4.5 卸载后重装仍报already exists现象明明卸载了重装还是提示目录已存在。原因卸载脚本没清干净缓存目录比如~/Library/Caches/Homebrew。解决手动删掉残留缓存目录再装别指望卸载脚本包办一切。5. 进阶把镜像配置固化成可复用习惯跑通一次不算完真正省心的是让这套配置在你换机器、重装系统、切换 shell 时都能快速复用。我现在的做法是把脚本写入的那几行环境变量单独抽出来存成一个小片段新机器上先贴这段再跑安装。# 把这几行存成 ~/.brew_mirror需要时 source 它 export HOMEBREW_BREW_GIT_REMOTE你的镜像地址 export HOMEBREW_CORE_GIT_REMOTE你的镜像地址 export HOMEBREW_BOTTLE_DOMAIN你的镜像地址 export HOMEBREW_API_DOMAIN你的镜像地址 # 注意具体地址以脚本实际写入的为准别照抄占位符逻辑说明把镜像变量独立成文件好处是升级 brew 或换 shell 时不用重新翻脚本source ~/.brew_mirror一行搞定。参数上四个变量分别对应仓库、core tap、bottle、API缺一不可这是我踩过最多次的坑——总以为换一个就够。验证配置是否长期有效我一般用两个动作一是brew config看四项源是否都指向镜像二是隔一段时间跑brew update brew upgrade观察是否稳定。如果某天突然变慢先怀疑镜像地址失效而不是怀疑 brew 坏了。还有一个容易被忽略的点error.md这个文件别删。它记录的是作者遇到过的真实报错我第二次装的时候就靠它定位了权限问题。从那以后我每次在新机器上装 brew都强制走一遍「先看 error.md → 再跑 installGIT.sh → 最后跑主脚本」的顺序再没出现过装到一半崩掉的情况。希望这套流程也能帮你少重装几次。本文还有配套的精品资源点击获取