homebrew 在 macos 上因 github 网络限制导致下载慢、超时、curl 错误等问题，可通过中科大或清华镜像源快速解决：安装前设环境变量并用镜像脚本安装，或已安装后逐项替换仓库地址与 bottles 域名，apple silicon 用户需额外配置 shell 环境。
如果您在 macOS 上安装或使用 Homebrew 时遇到下载缓慢、超时中断、curl 错误（如 curl: (7) Failed to connect to raw.githubusercontent.com）、HTTP/2 stream was not closed cleanly: PROTOCOL_ERROR 或 404 Not Found 镜像失效 等问题，则极大概率是因默认源托管于 GitHub，受跨境网络限制所致。以下是多种可立即生效的换源与故障解决方法：
一、安装阶段直接使用镜像源（推荐新手）
此方法跳过官方慢速脚本，在执行安装前即完成镜像配置，避免安装中途卡死在克隆 homebrew-core 环节。适用于尚未安装 Homebrew 的用户。
1、打开终端，一次性执行中科大镜像环境变量设置命令：
2、复制并粘贴以下全部内容，回车运行：
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
3、执行定制化安装脚本：
/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"
4、等待输出 ==> Installation successful! 即表示核心安装完成。
5、Apple Silicon（M1/M2/M3）用户必须执行环境变量写入：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
6、验证安装结果：
brew --version
二、已安装 Homebrew 后更换镜像源（覆盖式配置）
此方法针对已通过官方脚本安装但运行缓慢或频繁报错的用户，通过逐项替换各组件远程地址实现全链路加速，确保 brew update、brew install 均从国内镜像拉取。
1、替换 Homebrew 核心仓库地址：
git -C "$(brew --repo)" remote set-url origin https://mirrors.ustc.edu.cn/brew.git
2、替换 homebrew-core 公式仓库地址：
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
3、替换 homebrew-cask 图形应用仓库地址（可选但建议）：
git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
4、设置 bottles 预编译包镜像域名：
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.zshrc
5、重新加载配置文件：
source ~/.zshrc
6、强制刷新仓库缓存并验证：
brew update
7、检查当前源是否生效：
git -C "$(brew --repo)" remote get-url origin
三、使用清华镜像源一键切换（兼容性更强）
清华大学 TUNA 镜像站对 Apple Silicon 支持更完善，且部分版本对 HTTPS 证书校验更宽松，适合在中科大源出现 SSL certificate problem 时作为替代方案。
1、执行以下命令一次性切换全部组件为清华源：
git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git
2、切换 homebrew-core：
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git
3、切换 homebrew-cask：
电脑手机电子配件电子商城网站模板是一款提供手机、手表、电脑等电子配件和设备的电子商城宣传网站模板下载。提示：本模板调用到谷歌字体库，可能会出现页面打开比较缓慢。
git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git
4、设置清华 bottles 地址：
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles' >> ~/.zshrc
5、重载配置并更新：
source ~/.zshrc
brew update
四、手动修改安装脚本并本地执行（断网/高防火墙环境适用）
当 curl 命令完全无法连接 raw.githubusercontent.com 或 ghcr.io 时，可将官方安装脚本下载至本地，手动替换所有远程地址后再执行，规避网络拦截。
1、在终端中创建临时安装文件：
curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh >> brew_install.sh
2、用 nano 编辑该文件：
nano brew_install.sh
3、查找并替换以下两处地址（按 Ctrl+W 输入关键词搜索）：
原内容：BREW_REPO = "https://github.com/Homebrew/brew"
替换为：BREW_REPO = "https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
4、继续查找关键词 HOMEBREW_CORE_REPO，将其值替换为：
"https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
5、保存退出（nano 中按 Ctrl+O → 回车 → Ctrl+X）：
6、赋予执行权限：
chmod +x brew_install.sh
7、执行本地脚本：
./brew_install.sh
五、修复常见安装中断故障（homebrew-core 克隆失败专项）
若安装过程中卡在 Cloning into '/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core'，说明 core 仓库克隆失败，需手动初始化并指定镜像地址，否则 brew install 将持续报错“no formula found”。
1、中断当前安装流程（Ctrl+C）：
2、创建 Taps 目录结构（如不存在）：
mkdir -p /usr/local/Homebrew/Library/Taps/homebrew
3、进入该目录：
cd /usr/local/Homebrew/Library/Taps/homebrew
4、手动克隆 homebrew-core 镜像（中科大源，带深度优化）：
git clone https://mirrors.ustc.edu.cn/homebrew-core.git --depth=1 homebrew-core
5、进入刚克隆的目录并设置远程地址：
cd homebrew-core
git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
6、返回 Homebrew 根目录并设置全局 bottles 地址：
cd $(brew --repo)
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.zshrc
7、重载并验证：
source ~/.zshrc
brew doctor
