简介：这份资源是面向国内 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 | 检查并安装 Git（Xcode 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 tap：
HOMEBREW_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/homebrew（Apple Silicon）或/usr/local（Intel）有写权限；第三，确认终端能正常访问镜像地址。
# 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 → 最后跑主脚本」的顺序，再没出现过装到一半崩掉的情况。希望这套流程也能帮你少重装几次。
本文还有配套的精品资源，点击获取
