简介这份资源是面向国内 macOS 用户的 Homebrew 国内安装脚本合集主要解决官方源下载缓慢甚至无法访问的问题。包内共 12 个文件以 5 个 sh 脚本、3 个 md 说明文档为主另含 2 张 jpg 运行截图、1 个 license 及 1 个 .DS_Store压缩包约 458KB。脚本涵盖安装、卸载、Git 环境准备等环节可自动将 Homebrew 源切换为国内镜像并配置相关环境变量帮助开发者与命令行初学者更顺畅地完成安装与后续软件管理。文档部分提供使用说明与常见问题参考截图则直观展示运行过程便于对照排查。目前已有 1203 人学习下载适合希望提升 Homebrew 安装与更新效率、减少网络等待时间的用户参考使用。1. Homebrew 国内安装脚本为什么你的 mac 装个包管理器比装系统还慢如果你在 mac 上敲下官方那行安装命令然后盯着终端里那个Press RETURN to continue or any other key to abort发呆超过十分钟最后等来一个Failed to connect to raw.githubusercontent.com port 443那你不是一个人。Homebrew 本身是个好东西macOS 上缺了它装个wget、jq、ffmpeg都得手动编译但它的安装脚本和后续的 formula 索引默认都指向境外源国内网络环境下经常卡在第一步。所谓「Homebrew 国内安装脚本」本质就是把这个安装过程里的几个网络请求点换成国内可达的镜像让brew能正常落地而不是去改 Homebrew 本身的逻辑。这件事适合两类人一是刚换 mac 的后端或数据方向从业者想快速把开发环境搭起来二是已经装过但被brew update卡到想砸键盘、想彻底重来一遍的人。下面按「先搞清楚它在干什么 → 怎么换源装 → 装完怎么配 → 哪里容易翻车」的顺序讲每一步都能直接抄。2. 安装脚本到底改了哪几个网络请求点2.1 官方安装脚本的三段式结构Homebrew 的安装脚本本身是一个 bash 脚本从官方地址拉下来之后执行。它干的事分三段第一段是检查系统环境确认你是 macOS 还是 Linux、有没有装 Xcode Command Line Tools第二段是git clone两个仓库一个是核心的brew.git一个是homebrew-core.git这两个仓库体积不小国内直连基本没戏第三段是配置环境变量把brew的可执行文件路径写进 shell 的配置文件里。很多人以为卡住是脚本本身下载慢其实脚本文件很小真正卡的是第二段的git clone。所以「国内安装脚本」的核心思路不是重写脚本而是把git clone的源地址替换成国内镜像同时把后续brew update用的 API 地址也一并换掉。2.2 镜像源的选择与当前可用性判断国内做 Homebrew 镜像的机构换过好几轮早期大家用中科大和清华的 git 镜像后来因为仓库体积和同步频率问题部分镜像停掉了 git 方式转向了 API 方式。当前比较稳的做法是安装阶段用镜像的 git 地址完成初始 clone装完之后把HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN指向镜像的 API 和 bottle 地址。判断一个镜像还能不能用不要只看它首页写没写「Homebrew 镜像」直接curl -I一下它的 git 地址和 API 地址看返回码是不是 200。我一般会同时准备两个镜像一个主用一个备用因为镜像同步偶尔会挂挂的时候brew update会报Not Found或者Could not resolve host这时候切备用能省很多时间。2.3 环境变量在安装前后的作用差异这里有个容易搞混的点安装前设置的环境变量和安装后设置的环境变量作用范围不一样。安装前你 export 的HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE只影响安装脚本执行的那一次 clone安装完成后这两个变量如果没写进 shell 配置文件下次开终端就没了brew update又会走默认源。所以完整的做法是安装时用一组变量安装后把另一组变量API 和 bottle 相关写进~/.zshrc或~/.bash_profile让它们持久化。下面直接给可执行的步骤。3. 用国内镜像跑通 Homebrew 安装的最小命令集3.1 安装前设置 git 镜像并执行脚本先确认你的 shell 是 zsh 还是 bashmacOS 现在默认 zsh。然后按下面这段来注意把镜像地址换成你实际验证过可用的那个。这里以中科大镜像的路径格式为例但你要自己curl确认一下当前是否还在服务。# 设置安装阶段使用的 git 镜像地址 export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git # 拉取安装脚本并执行-c 后面是脚本内容这里用官方脚本的国内可达地址 # 如果这个地址也不通就手动把脚本下载到本地再 bash 执行 /bin/bash -c $(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)这段代码的逻辑是前两个 export 告诉安装脚本clone 仓库时不要走 GitHub走中科大。第三个命令是拉取安装脚本并执行。参数说明HOMEBREW_BREW_GIT_REMOTE对应核心仓库HOMEBREW_CORE_GIT_REMOTE对应 formula 仓库两个都要设少一个就会有一个仓库走默认源然后卡住。执行过程中如果提示要装 Xcode Command Line Tools按提示走这一步没法跳过但通常很快。3.2 安装后把 API 和 bottle 源写进 shell 配置安装脚本跑完之后brew命令能用了但brew update和brew install下载预编译包bottle时还是会走默认地址。需要把下面这组变量追加到~/.zshrc末尾然后source一下。# 追加到 ~/.zshrc让每次开终端都生效 cat ~/.zshrc EOF export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_NO_AUTO_UPDATE1 EOF # 让配置立即生效 source ~/.zshrc逻辑说明HOMEBREW_API_DOMAIN控制brew update时拉取 formula 索引的地址HOMEBREW_BOTTLE_DOMAIN控制下载预编译包的地址这两个是装完之后最影响体验的。HOMEBREW_NO_AUTO_UPDATE1是关掉每次brew install前的自动更新国内环境下自动更新经常卡住关掉之后手动brew update更可控。参数怎么改如果你用的不是中科大把域名换成对应镜像的域名路径部分一般镜像文档会写清楚不要自己猜。3.3 验证安装是否真的走通了国内源装完不要急着装软件先跑三条命令验证。第一条brew --version看版本号出不出来第二条brew config看输出里的HOMEBREW_BOTTLE_DOMAIN和HOMEBREW_API_DOMAIN是不是你设的镜像地址第三条brew install jq装一个小工具观察下载速度。如果brew config里显示的还是https://formulae.brew.sh或者https://ghcr.io说明环境变量没生效检查是不是写错了文件或者没source。这一步是分水岭验证过了后面基本顺畅没过的话后面每一步都会卡。4. 装完之后必调的三个参数与常见误用4.1 HOMEBREW_NO_AUTO_UPDATE 该不该开这个参数争议比较大。官方默认每次brew install前会先brew update目的是保证 formula 索引最新。但国内环境下这个自动更新经常因为 API 地址响应慢而卡几十秒甚至超时导致你只是想装个wget却等了五分钟。我一般会开HOMEBREW_NO_AUTO_UPDATE1然后每周手动brew update一次。手动更新时如果卡住可以加HOMEBREW_NO_INSTALL_FROM_API1临时切回 git 方式拉索引虽然慢但不容易断。注意这个参数只影响自动更新不影响brew install本身下载 bottle。4.2 HOMEBREW_BOTTLE_DOMAIN 的路径陷阱很多人设了HOMEBREW_BOTTLE_DOMAIN但下载还是走默认源原因是路径写错了。这个变量应该只写到域名加基础路径不要带/bottles后面的具体文件路径。比如中科大的格式是https://mirrors.ustc.edu.cn/homebrew-bottlesHomebrew 会自动在后面拼上bottles/和文件名。如果你写成https://mirrors.ustc.edu.cn/homebrew-bottles/bottles就会变成双份bottles导致 404。判断方法设完之后brew install一个包看下载 URL 里bottles出现了几次出现两次就是写多了。4.3 卸载残留导致重装失败怎么清如果你之前装过 Homebrew 但没装干净再跑安装脚本会报Homebrew is already installed或者 clone 到一半失败。这时候需要手动清残留。常见残留位置有/opt/homebrewApple Silicon和/usr/local/HomebrewIntel以及~/.cache/Homebrew。清理命令如下执行前确认这些目录里没有你还想保留的东西。# 删除 Homebrew 主目录按你的芯片类型选一个 sudo rm -rf /opt/homebrew sudo rm -rf /usr/local/Homebrew # 删除缓存和配置文件 rm -rf ~/.cache/Homebrew rm -rf ~/Library/Caches/Homebrew # 从 shell 配置里删掉之前加的 brew 相关行 # 手动编辑 ~/.zshrc删掉 eval $(/opt/homebrew/bin/brew shellenv) 这类行逻辑说明/opt/homebrew是 M 系列芯片的默认安装位置/usr/local/Homebrew是 Intel 芯片的。两个都删掉不影响系统但如果你在里面装过软件软件也会没。~/.cache/Homebrew存的是下载的 bottle 缓存删掉只是下次重新下载。清完之后重新走第 3 章的安装步骤就能干净重来。5. 避坑国内装 Homebrew 最容易翻车的五个点5.1 现象安装脚本卡在Cloning into /opt/homebrew不动原因HOMEBREW_BREW_GIT_REMOTE没设或者设的镜像地址已经失效脚本回退到了 GitHub 默认地址国内直连 clone 大仓库基本会卡死。解决CtrlC 中断确认镜像地址curl -I返回 200重新 export 两个 git 变量再跑脚本。如果镜像的 git 服务已经停了改用 API 方式安装即先通过镜像的安装脚本完成初始安装再设 API 变量。5.2 现象brew update报Error: Fetching /opt/homebrew/Library/Taps/homebrew/homebrew-core failed原因之前用 git 方式 clone 的 homebrew-core 仓库后来镜像停掉了 git 同步本地仓库和远程对不上。解决删掉本地 tap 目录rm -rf /opt/homebrew/Library/Taps/homebrew/homebrew-core然后设好HOMEBREW_API_DOMAIN再brew update让它走 API 方式重新拉索引。这个坑很常见因为镜像策略从 git 转 API 是这两年的事。5.3 现象brew install下载 bottle 速度只有几十 KB/s原因HOMEBREW_BOTTLE_DOMAIN没设或者设了但被HOMEBREW_API_DOMAIN的默认值覆盖了。Homebrew 在某些版本里会优先用 API 返回的 bottle 地址如果 API 地址是默认的bottle 地址也会是默认的。解决两个变量一起设设完brew config确认然后brew install时加-v看实际下载 URL。如果 URL 还是ghcr.io说明变量没生效检查 shell 配置文件有没有被其他配置覆盖。5.4 现象装完brew命令找不到提示command not found: brew原因安装脚本最后一步是把brew路径写进 shell 配置但如果你用的 shell 不是 zsh或者配置文件路径不对这一步会静默失败。解决手动确认brew可执行文件在不在Apple Silicon 在/opt/homebrew/bin/brewIntel 在/usr/local/bin/brew。在的话手动加一行eval $(/opt/homebrew/bin/brew shellenv)到你的 shell 配置文件source一下。不在的话说明安装没完成回第 3 章重来。5.5 现象brew doctor报一堆 warning说Homebrews prefix is not writable原因/opt/homebrew或/usr/local/Homebrew的权限不对通常是之前用sudo跑过brew命令导致的。解决不要用sudo brew永远不要。修复权限sudo chown -R $(whoami) /opt/homebrewIntel 机器换成/usr/local/Homebrew和/usr/local/bin。改完再brew doctorwarning 会少很多。这个坑的血泪经验是一旦用 sudo 跑过 brew后面会不断出权限问题趁早改回来。6. 进阶用 brew bundle 把环境配置变成可复现的清单装好 Homebrew 只是第一步真正省时间的是把你要装的软件写成Brewfile换机器或者重装系统时一条命令恢复。brew bundle是 Homebrew 自带的功能不需要额外装。下面是一个典型的开发环境Brewfile示例包含命令行工具、语言运行时和几个 GUI 应用。# Brewfile tap homebrew/cask tap homebrew/cask-fonts # 命令行工具 brew git brew wget brew jq brew ripgrep brew fd brew bat # 语言运行时 brew python3.12 brew node brew go # GUI 应用 cask visual-studio-code cask iterm2 cask docker用法把这个文件放在~/Brewfile然后brew bundle install --file~/Brewfile。它会检查哪些已经装了、哪些没装只装缺的。参数说明--file指定清单路径不加的话默认找当前目录的Brewfile。tap行是添加第三方仓库brew行是命令行工具cask行是 GUI 应用。如果你在国内cask下载大文件时可能慢可以配合HOMEBREW_BOTTLE_DOMAIN一起用但 cask 的下载地址不一定走 bottle 域名这点要有心理预期。验证方法跑完brew bundle install之后用brew bundle check --file~/Brewfile看是否全部满足输出The Brewfiles dependencies are satisfied就说明清单和实际环境一致。如果报缺某个包单独brew install补上再跑一次 check。这个习惯我保持了三年每次换 mac 或者帮同事配环境都是先拷Brewfile再跑一条命令比回忆「我上次装了啥」靠谱得多。希望帮到你。本文还有配套的精品资源点击获取