简介这份资源是面向国内 macOS 用户的 Homebrew 国内安装脚本合集主要解决官方源下载缓慢、安装失败等痛点适合需要频繁使用命令行工具的开发者和运维人员。压缩包共 12 个文件约 458KB以 5 个 sh 脚本为主涵盖安装、卸载、Git 安装等流程另附 3 个 md 说明文档、2 张运行过程截图、LICENSE 及系统隐藏文件结构清晰便于直接执行。脚本会自动将 Homebrew 源切换为国内镜像并配置相关环境变量从而显著提升安装与更新速度。资源还包含国外版本脚本与错误说明文档方便对比排查问题。目前已有 1206 人学习下载适合希望快速完成 Homebrew 部署、减少等待时间的中初级用户参考使用。1. Homebrew 国内安装脚本为什么你照着官网敲命令总是卡住如果你在 Mac 上敲过官网那行安装命令大概率见过两种结局要么卡在Cloning into /usr/local/Homebrew...一动不动要么直接报Failed to connect to raw.githubusercontent.com port 443。这不是你网络的问题也不是命令敲错了而是 Homebrew 的安装脚本默认从境外源拉取仓库和二进制包国内直连基本靠运气。所谓「Homebrew 国内安装脚本」本质就是把官方 install.sh 里的仓库地址、API 域名、二进制瓶bottle下载源替换成国内可达的镜像让整个安装链路在本地网络环境下能跑通。它解决的是「mac 安装 homebrew 失败」这个高频痛点适合三类人刚拿到新 Mac 想快速配好开发环境的新手、被墙外源反复折磨的老用户、以及需要批量给团队机器初始化环境的运维。下面我按自己踩过的坑把选源、装、配、排错整条链路讲清楚。2. 国内安装脚本到底改了什么镜像源与安装链路拆解2.1 官方安装脚本的三段网络请求要理解国内脚本为什么有效得先知道官方 install.sh 干了哪三件事。第一段它用git clone把Homebrew/brew仓库拉到本地这是最常卡住的地方因为 GitHub 的 raw 和 git 协议在国内经常超时。第二段它把Homebrew/homebrew-core等核心仓库 clone 下来这些仓库体积大直连几乎不可能完成。第三段安装完成后brew install下载的预编译二进制包bottle默认从ghcr.io拉取同样慢。国内安装脚本的思路很直接把这三段请求的地址全部换成国内镜像。常见做法是使用中科大USTC、清华TUNA或阿里云的镜像。以中科大为例它同时提供 git 仓库镜像和 bottle 镜像覆盖了完整链路。清华源的优势是文档全、更新及时阿里云源在企业内网环境下稳定性更好。选哪个没有绝对答案我一般先试中科大不通再换清华。提示镜像源不是越多越好混用不同镜像的 git 和 bottle 地址偶尔会出现版本对不上的玄学问题建议 git 和 bottle 用同一家。2.2 环境变量注入脚本的核心机制国内脚本真正做的事是在安装前把一组环境变量导出到当前 shell让 Homebrew 的安装器和后续的 brew 命令都读取这些变量。关键变量有四个变量名作用典型值HOMEBREW_BREW_GIT_REMOTE指定 brew 主仓库的 git 地址中科大 brew.git 镜像HOMEBREW_CORE_GIT_REMOTE指定 core 仓库的 git 地址中科大 homebrew-core.git 镜像HOMEBREW_API_DOMAIN指定 API 域名新版 brew 用它查包信息中科大 API 镜像地址HOMEBREW_BOTTLE_DOMAIN指定 bottle 二进制包下载源中科大 bottles 镜像地址这四个变量覆盖了前面说的三段请求。脚本通常还会设置HOMEBREW_NO_AUTO_UPDATE1避免安装过程中自动更新又去连境外源。理解这几个变量后面出问题你才知道该查哪个。2.3 手动执行与脚本执行的差别很多人以为必须下载一个「脚本文件」才能装其实这些环境变量你手动 export 再跑官方 install.sh 效果一样。脚本只是把这一串 export 和安装命令打包了。手动执行的好处是每一步你都看得见出问题好定位脚本执行的好处是快、可复用。我建议第一次装的时候手动来一遍搞清楚每个变量在干嘛之后再写成脚本给团队用。3. 手把手跑通国内源安装从零到 brew 可用3.1 安装前的环境检查动手前先确认两件事。一是你的 Mac 有没有装 Xcode Command Line ToolsHomebrew 依赖它里面的编译工具。终端执行xcode-select -p如果返回一个路径说明已装如果报错先执行xcode-select --install弹窗点安装等它下完。二是确认你的 shell 类型这决定环境变量写哪个配置文件echo $SHELL返回/bin/zsh就是 zshmacOS 默认返回/bin/bash就是 bash。后面配置持久化环境变量时zsh 写~/.zshrcbash 写~/.bash_profile。这一步别跳过我见过有人变量写错文件装完重启终端又失效了回头找半天原因。3.2 用中科大源手动安装的完整命令下面这套命令是我在多个 macOS 版本上验证过的逐段执行别一次性粘贴# 1. 设置 brew 主仓库和 core 仓库的 git 镜像 export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git # 2. 设置 API 域名和 bottle 下载源 export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles # 3. 关闭安装过程中的自动更新避免又去连境外源 export HOMEBREW_NO_AUTO_UPDATE1 # 4. 执行官方安装脚本此时它会读取上面的变量走镜像 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)逻辑说明前四行 export 只对当前终端会话生效第五行才是真正触发安装。安装脚本内部会读取HOMEBREW_BREW_GIT_REMOTE等变量把原本指向 GitHub 的 clone 操作重定向到中科大。参数说明HOMEBREW_API_DOMAIN是较新版本 brew 才用的老版本可能忽略它不影响安装HOMEBREW_NO_AUTO_UPDATE1建议保留能省掉很多等待。注意第四步的 install.sh 本身还是从 raw.githubusercontent.com 拉的如果这一步就卡住说明你连脚本都下不下来。解决办法是换用国内镜像托管的 install.sh或者先配置好能访问该域名的网络环境再执行。3.3 安装后把环境变量固化到配置文件上面 export 的变量关掉终端就没了brew install时又会去连境外 bottle 源。所以装完必须把它们写进 shell 配置文件。zsh 用户执行# 把镜像配置追加到 ~/.zshrc cat ~/.zshrc EOF 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_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逻辑说明cat 是追加写入不会覆盖你已有的配置。用 EOF这种 heredoc 写法单引号保证变量名不被提前展开。写完 source 一下当前终端就生效了。参数说明如果你用的是 bash把~/.zshrc换成~/.bash_profile即可。这一步做完可以执行brew config看输出里的HOMEBREW_BOTTLE_DOMAIN是否指向了镜像确认配置生效。3.4 验证安装是否真的走通了装完别急着用先跑三条验证命令# 1. 看 brew 版本和配置 brew config # 2. 装一个小包测试 bottle 下载是否走镜像 brew install wget # 3. 看 wget 是否可用 wget --versionbrew config会打印一堆配置重点看HOMEBREW_BOTTLE_DOMAIN和HOMEBREW_API_DOMAIN两行是不是你的镜像地址。brew install wget是压力最小的实测如果几秒内开始下载且速度正常说明 bottle 源配对了。如果这里又卡住回到 3.3 检查变量有没有写对文件、有没有 source。4. 换源、卸载与残留清理那些没人告诉你的坑4.1 换源后 brew update 报错的排查换了镜像源之后brew update偶尔会报fatal: unable to access ...或者Not a git repository。现象是更新直接失败原因通常是之前用官方源装过本地 git 仓库的 remote 还指向 GitHub而你只改了环境变量没改 remote。解决办法是手动改 remote# 进入 brew 仓库目录改 remote 地址 git -C $(brew --repository) remote set-url origin https://mirrors.ustc.edu.cn/brew.git # core 仓库同理 git -C $(brew --repository homebrew/core) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git改完再brew update就正常了。这个坑的根源是环境变量只影响新 clone不影响已存在的仓库 remote。4.2 卸载 Homebrew 与残留目录清单「homebrew卸载残留」是高频搜索词因为官方卸载脚本删不干净。官方脚本只删主目录但缓存、日志、配置散落在多处。彻底清理要手动删这几个位置路径内容是否必删/opt/homebrewApple Silicon或/usr/local/HomebrewIntelbrew 主目录是~/Library/Caches/Homebrew下载缓存可能几个 G是~/Library/Logs/Homebrew安装日志建议~/.zshrc里的 HOMEBREW 变量环境变量残留是清理命令# Apple Silicon 机器 rm -rf /opt/homebrew rm -rf ~/Library/Caches/Homebrew rm -rf ~/Library/Logs/Homebrew # 然后手动编辑 ~/.zshrc删掉所有 HOMEBREW_ 开头的行注意删/opt/homebrew前确认没有其他工具依赖它比如某些通过 brew 装的命令行工具。删完记得把~/.zshrc里相关的 PATH 配置也清掉否则新终端会报command not found之类的 PATH 错误。4.3 避坑清单五个真实翻车记录现象一安装卡在Cloning into /opt/homebrew...超过十分钟。原因环境变量没生效脚本还在连 GitHub。解决确认 export 命令和 install.sh 在同一个终端会话执行中间没开新窗口。现象二brew install报Error: SHA256 mismatch。原因混用了不同镜像的 git 源和 bottle 源导致包元数据和二进制对不上。解决git 和 bottle 统一用同一家镜像清掉~/Library/Caches/Homebrew重试。现象三装完新开终端brew命令找不到。原因Apple Silicon 的 brew 装在/opt/homebrew/bin这个路径没加进 PATH。解决在~/.zshrc加eval $(/opt/homebrew/bin/brew shellenv)source 生效。现象四brew update提示homebrew-core is a shallow clone。原因国内镜像的 core 仓库是浅克隆brew 想转成完整克隆。解决执行git -C $(brew --repository homebrew/core) fetch --unshallow或者忽略这个提示不影响使用。现象五卸载后重装报目录已存在。原因上次卸载没删干净残留目录让安装脚本以为已装。解决按 4.2 的清单彻底删干净再重装。5. 把安装脚本写成团队可复用的一键方案单人装一次手动敲命令没问题但如果你要给团队十几台机器初始化或者自己经常重装系统就该把它固化成一个脚本。我的习惯是写一个install-brew.sh把环境检查、变量设置、安装、验证串起来新机器上bash install-brew.sh一把梭。核心结构是这样#!/bin/bash set -e # 任何一步失败就退出避免带病往下跑 # 1. 检查 Xcode CLT if ! xcode-select -p /dev/null 21; then echo 请先安装 Xcode Command Line Tools xcode-select --install exit 1 fi # 2. 设置镜像变量这里用中科大可换成清华 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_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_NO_AUTO_UPDATE1 # 3. 执行安装 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) # 4. 把变量写入 zshrc幂等先删旧的再加 sed -i /HOMEBREW_/d ~/.zshrc 2/dev/null || true cat ~/.zshrc EOF 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_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_NO_AUTO_UPDATE1 eval $(/opt/homebrew/bin/brew shellenv) EOF echo 安装完成请执行 source ~/.zshrc 生效这个脚本有两个细节值得说。set -e保证任何一步失败立即停不会出现「Xcode 没装却硬装 brew」的连锁错误。第 4 步的sed -i 是 macOS 特有的写法Linux 上是sed -i先删掉旧的 HOMEBREW 行再追加保证脚本重复执行不会把配置写重复这叫幂等。最后那行eval $(/opt/homebrew/bin/brew shellenv)是 Apple Silicon 机器必须的它把 brew 的 bin 目录加进 PATH不加的话新终端里 brew 命令找不到。验证脚本是否成功不用重装跑一条brew doctor就行。它会检查你的 brew 环境有没有问题输出Your system is ready to brew.就说明一切正常。如果它报一堆 warning按提示逐条处理大部分是 PATH 或权限问题。我自己的习惯是把这个脚本和一份Brewfile放一起。Brewfile里列出团队统一要装的工具脚本装完 brew 后自动brew bundle新机器从开箱到环境齐活十分钟内搞定。这套东西我用了两年多唯一一次翻车是某台机器之前装过旧版 brewremote 没改导致 update 失败按 4.1 的方法改 remote 就好了。所以脚本里最好再加一步检测已有安装、自动改 remote 的逻辑才算真正健壮。希望帮到你。本文还有配套的精品资源点击获取