很多新 Mac 用户拿到机器第一件事就是装 Homebrew。这个包管理器对 macOS 开发人群来说基本等于“半条命”装 wget、装 git、装 node、装各种命令行工具全靠它。但偏偏 Homebrew 的官方安装脚本在国内网络环境下经常卡死下载几个核心仓库的速度也是时快时慢装到一半报错、更新半天没反应都是常态。这篇文章我按 2026 年当前最新几个 macOS 大版本的实际操作方式把 Homebrew 安装、换源以及 Git 环境配置的完整流程重新捋了一遍。内容偏保姆级几乎是“复制命令就能跑”的程度同时把你可能会遇到的报错和解决办法也一并整理了。适合两类人刚拿到新 Mac 准备配开发环境的小白以及在旧机器上被 Homebrew 折腾到想卸了重装的老朋友。1. 动手前的准备先搞清楚自己这台 Mac 的状态1.1 查看系统版本与芯片架构Homebrew 的安装路径、目录权限、镜像选择多多少少跟芯片架构有关系。Apple Silicon 芯片M1/M2/M3/M4 系列和 Intel 芯片在安装目录上并不一样前者装在 /opt/homebrew后者装在 /usr/local。如果你不清楚自己的机器是哪一类打开终端执行uname -m返回 arm64 就是 Apple Silicon返回 x86_64 就是 Intel。接着再看系统版本sw_vers这两条命令花不到十秒钟但能省掉后面很大一部分困惑。我见过不少人拿着别人分享的配置脚本直接复制结果因为架构不同路径对不上终端一直提示 command not found排查半天才发现是目录差异。1.2 安装 Xcode 命令行工具Homebrew 和 Git 都依赖 macOS 自带的 Xcode Command Line Tools简称 CLT。它提供编译工具链、Git 的底层依赖以及一些必要的系统库。没有它Homebrew 装任何带编译过程的软件都会报错。在终端执行xcode-select --install系统会弹窗提示安装确认后等它下载完成即可。已经装过的话终端会提示 “command line tools are already installed”那不是报错是好事。验证 CLT 是否可用看这两个命令的输出xcode-select -p clang --version只要不报 “unable to find” 之类的错误就说明工具链已经就绪。需要注意这里装的是命令行工具不是 App Store 里那个几十 GB 的完整 Xcode。除非你要搞 iOS 开发否则 CLT 完全够用没必要提前占几十 GB 的硬盘空间。1.3 确认 shell 与终端环境macOS 从 Catalina 开始默认 shell 是 zsh配置文件是 ~/.zshrc。你在网上搜到的很多配置教程会直接让你往这个文件里写内容但如果你曾经手动改过默认 shell或者机器是从旧版本升级上来的配置文件可能是 ~/.bash_profile那就对不上了。先确认当前 shellecho $SHELL看到 /bin/zsh 就按 zsh 的配置路径来。接着检查配置文件是否存在ls -la ~/.zshrc如果文件不存在第一次配置前建一个就行。后面所有需要持久化的环境变量我都会放到这个文件里。动手之前还有一个最基本的动作把终端里已有的重要配置备份一下。不是每个人都记得自己当年往 .zshrc 里塞了什么等到出了问题再后悔当初没备份那就晚了。cp ~/.zshrc ~/.zshrc.bak这一步没有成本但对后续所有操作都是一个安全网。2. Homebrew 安装全流程从官方脚本到镜像加速2.1 官方一键安装脚本到底卡在哪里Homebrew 官方给的安装命令非常精简/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)看起来一条命令搞定实际执行过程要完成好几件事。首先从 raw.githubusercontent.com 下载安装脚本本身然后创建目标目录再从 GitHub 拉取 brew、homebrew-core、homebrew-cask 三个仓库的代码最后设置目录权限、写入环境变量配置。问题恰恰就出在这些环节上。国内网络环境下raw.githubusercontent.com 域名解析和连接速度经常不稳定脚本下载失败是常见的第一个坎。就算脚本下载成功后面从 GitHub 拉取三个仓库时连接也很容易中途断开或者长时间停留在 “Updating” 状态看起来像卡死了一样。理解了卡点在哪解决思路就清楚了下载脚本失败的想办法用能稳定访问的方式把脚本拿到手仓库拉取慢的把 git remote 地址换成国内镜像源。下面整个安装流程就是围绕这两点展开的。2.2 官方安装脚本到底做了什么先搞清楚脚本的内部逻辑后面遇到报错才知道怎么处理。官方 install.sh 的执行流程大致如下检查系统版本是否满足要求检查 Xcode Command Line Tools 是否已安装创建 Homebrew 主目录Apple Silicon 是 /opt/homebrewIntel 是 /usr/local/Homebrew用 git clone 拉取 Homebrew/brew、Homebrew/homebrew-core、Homebrew/homebrew-cask 三个仓库调整目录所有者权限让当前用户可以直接读写在 ~/.zshrc 或 ~/.bash_profile 中写入 PATH 相关配置运行 brew update 和几个基本自检项。这里最关键的是第三和第四步。创建目录需要管理员权限脚本内部会用 sudo 的方式操作所以安装过程中让你输入密码是正常的。而 clone 仓库这一步走的是 GitHub 官方地址也就是最容易卡住的地方。2.3 镜像源选哪个清华、中科大、阿里云横向对比所谓换源就是把 Homebrew 默认访问的 GitHub 仓库地址替换成国内高校或云厂商维护的镜像地址。这些镜像会定期同步 Homebrew 官方仓库和编译好的二进制包速度和稳定性都比直连 GitHub 好很多。我整理了几个常用镜像源的信息都是公共镜像可以放心使用镜像源Homebrew 主仓库地址Bottle 包地址特点清华 TUNAmirrors.tuna.tsinghua.edu.cn/git/homebrewmirrors.tuna.tsinghua.edu.cn/homebrew-bottles同步快文档全适合教育网和家庭宽带中科大 USTCmirrors.ustc.edu.cn/brew.gitmirrors.ustc.edu.cn/homebrew-bottles老牌镜像稳定国内访问速度好阿里云mirrors.aliyun.com/homebrewmirrors.aliyun.com/homebrew/homebrew-bottles云厂商线路商业网络下稳定选哪个其实都可以没必要纠结太久。我个人常用的习惯是教育网环境优先清华普通家庭宽带优先阿里云。如果你第一套镜像安装失败换个源再试不用死磕。2.4 用镜像环境变量安装一次到位现在最稳妥的方式不是去找网上的修改版安装脚本而是先设置好环境变量再运行官方原版安装脚本。Homebrew 官方在安装阶段支持通过环境变量覆盖仓库地址这也是 2026 年主流镜像站文档里推荐的做法。以清华源为例打开终端按顺序执行export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles这三个变量分别指定了 brew 主仓库、homebrew-core 公式仓库以及预编译二进制包的下载域名。设置完再运行官方脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)脚本下载那一步如果也超时可以在浏览器里打开上面那个 install.sh 地址把内容保存到本地文件再执行/bin/bash /path/to/install.sh脚本本体就是一个文本文件本地执行和 curl 远程执行没有本质区别。这一步安装过程中会自动读取前面 export 的环境变量所以仓库拉取会走镜像速度会明显快起来。安装过程会要求输入密码这是脚本要创建 /opt/homebrew 目录并修改权限属于正常操作。安装完成后终端会提示你下一步怎么做看到 “Installation successful” 就说明装好了。2.5 安装后的检查PATH、版本、目录权限很多人在网上抱怨 “brew 装完了却提示 command not found”十有八九是 PATH 没有生效或者终端没重开。先确认 brew 命令能不能直接识别brew --version能输出版本号说明正常。如果提示 command not found检查 which brew 的路径which brewApple Silicon 机器正常路径应该是 /opt/homebrew/bin/brewIntel 机器是 /usr/local/bin/brew。如果 which 输出为空手动把 PATH 写进 ~/.zshrcecho export PATH/opt/homebrew/bin:$PATH ~/.zshrc source ~/.zshrcIntel 机器把 /opt/homebrew 换成 /usr/local 就行。还有一个容易忽略的细节安装完成后官方脚本会自动把配置写入 ~/.zshrc但如果你当前终端是在安装之前打开的环境变量还没读到重开一个终端窗口或者 source 一下就能解决不需要反复重装。3. Homebrew 换源让下载速度真正稳定下来3.1 换源的本质不只是换一个地址那么简单Homebrew 日常使用中要访问的远程资源不止一处。装命令工具时先通过 homebrew-core 仓库里的 formula 文件找到安装定义再从 bottle 镜像下载编译好的二进制包装 GUI 应用时走的是 homebrew-cask 仓库。如果只把某个源换了其他还是直连 GitHub那速度瓶颈依然存在。所以完整的换源方案要覆盖三块brew 主仓库、homebrew-core、homebrew-cask外加 bottle 下载域名。前面安装阶段设置的 HOMEBREW_BREW_GIT_REMOTE 和 HOMEBREW_CORE_GIT_REMOTE 只对安装过程有效装完之后的持久化配置需要单独处理。3.2 主仓库、Core、Cask 三个仓库逐个换换源本质是修改 Git remote操作可以用一组命令完成。先确认当前位置对应的仓库再执行 set-url。以下以清华镜像为例# 换 brew 主仓库 cd $(brew --repo) git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git # 换 homebrew-core cd $(brew --repo homebrew/core) git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git # 换 homebrew-cask cd $(brew --repo homebrew/cask) git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git执行完后可以检查一下是否生效cd $(brew --repo) git remote -v看到 remote 地址已经变成镜像源说明配置成功。这里有个很多人踩过的坑不同版本的 Homebrew 目录结构有差异直接 cd 到一个不存在的目录会报错。用 brew --repo 来定位目录不要手动拼路径这是最稳妥的做法。用中科大源的话把地址里的 tunas 换成 ustc 对应的路径即可阿里云同理。3.3 Bottle 下载地址持久化配置仓库源换完了还差 bottle 域名。因为 brew install 大部分软件时实际下载的是 bottle 包这一步不换装大软件时还是慢。把 HOMEBREW_BOTTLE_DOMAIN 写入 ~/.zshrc实现持久化echo export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles ~/.zshrc source ~/.zshrc同样如果你选择中科大用 mirrors.ustc.edu.cn/homebrew-bottles选择阿里云用 mirrors.aliyun.com/homebrew/homebrew-bottles。除了 bottle 域名我建议顺手加上几个实用的环境变量都写到 ~/.zshrc 里export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1 export HOMEBREW_NO_ANALYTICS1HOMEBREW_NO_AUTO_UPDATE 的意思是每次执行 brew install 时不自动运行 brew update。不关掉的话每次装软件都会先更新索引碰到源不稳定的情况一个安装命令能在 “Updating” 状态卡好几分钟。这个变量是我认为最值得开的开了之后安装体验会顺畅非常多。3.4 换源后怎么验证真的生效了换源不是换完就行要验证。最简单的方式是直接跑一次更新brew update如果能在十几秒内完成而不是长时间停在 “Updating Homebrew”说明仓库源生效了。接着查看 brew 实际读取的配置brew config输出里会列出 HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_BOTTLE_DOMAIN 等环境变量。如果显示的是镜像站地址就说明持久化配置被正确读取了。最后用实际安装验证下载速度。比如装一个常用工具brew install wget观察日志里的下载地址。如果出现 mirrors.tuna.tsinghua.edu.cn 这类域名说明 bottle 源也生效了。如果显示 GitHub 的地址回去检查 HOMEBREW_BOTTLE_DOMAIN 是否写进了 ~/.zshrc并且当前终端是否重新 source 过。3.5 源挂了或者想还原怎么办镜像站偶尔也会出问题最常见的是同步延迟、或者某天仓库索引缺失。这时候不要慌直接把远程地址切回 GitHub 官方源即可。# 还原 brew 主仓库 cd $(brew --repo) git remote set-url origin https://github.com/Homebrew/brew.git # 还原 homebrew-core cd $(brew --repo homebrew/core) git remote set-url origin https://github.com/Homebrew/homebrew-core.git # 还原 homebrew-cask cd $(brew --repo homebrew/cask) git remote set-url origin https://github.com/Homebrew/homebrew-cask.git环境变量相关的内容编辑 ~/.zshrc把 HOMEBREW_BOTTLE_DOMAIN、HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE 这几行删掉再 source 一下就恢复官方默认行为了。需要强调的是换源这个操作本身是可逆的建议在一开始就把原来的 remote 地址记录下来。动手前执行一遍 git remote get-url origin把输出存到备忘录里回头要还原的时候就不用到处找。4. Git 环境配置装好只是开始配置好才算可用4.1 系统自带的 Git 和 Homebrew 的 Git选哪个macOS 装完 Xcode CLT 之后系统里其实已经有一个 Git 了直接执行 git --version 就能看到。但这个版本往往比较保守功能更新也慢。用 Homebrew 装一个新版 Git好处是版本新、用 brew 管理方便升级。对你个人而言如果只是 commit、push、pull 这些基础操作系统自带的 Git 完全够用。但如果要体验新特性或者希望所有开发工具都统一用 brew 管理我建议用 Homebrew 装一个brew install git装完之后注意一个细节which git 显示的位置。正常应该是 /opt/homebrew/bin/git但有时候 PATH 顺序不对终端仍然优先使用系统自带的 /usr/bin/git。遇到这种情况检查 ~/.zshrc 里的 export PATH 是否在文件靠前的位置确保 /opt/homebrew/bin 在 /usr/bin 之前。4.2 Git 全局配置提交身份和环境设置安装本身不是重点重点在于配置。Git 刚装完不能直接舒服地用因为还没有设置提交身份。不设置的话每次 commit 都会报错或者生成一串不知道是谁的提交记录。设置全局用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱这两个信息会写进每个新仓库的提交记录建议用真实姓名和常用邮箱。如果你有隐私顾虑可以用 GitHub 的 noreply 邮箱但一句话说在前头邮箱改了历史提交里的旧邮箱不会变想清楚了再下手。除了用户名和邮箱我习惯把下面几项也一并设置好git config --global init.defaultBranch main git config --global pull.rebase false git config --global color.ui autoinit.defaultBranch main 让新建仓库默认主分支叫 main 而不是 master跟现在主流托管平台保持一致。pull.rebase false 保持默认的 merge 策略适合不熟悉 rebase 的初学者。color.ui auto 让终端输出带上颜色看 diff 和 status 会舒服很多。查看所有全局配置git config --global --list4.3 SSH Key 的生成、加载与托管平台接入Git 连接远程仓库有两种主流协议HTTPS 和 SSH。HTTPS 每次 push 可能要输入账号密码麻烦SSH 配置好之后密钥存在本地访问托管平台不用反复输密码而且更安全。生成密钥之前先看自己有没有已经存在的公钥ls -la ~/.ssh如果没有 id_ed25519 或 id_rsa 开头的一对文件就生成新的。现代新机器我推荐用 Ed25519性能好、安全性高ssh-keygen -t ed25519 -C 你的邮箱一路回车即可默认生成在 ~/.ssh/id_ed25519。设置 passphrase 是加分项但新手容易忘可以先留空。生成之后把公钥内容复制出来cat ~/.ssh/id_ed25519.pub复制输出的整行字符串到 GitHub、GitLab、Gitee 等托管平台的 SSH Keys 设置页添加进去。添加完之后测试连接ssh -T gitgithub.com第一次连接会提示确认 host key输入 yes 回车。看到 “successfully authenticated” 或类似提示就说明 SSH 通道已经通了。如果系统没有自动加载密钥测试时提示 Permission denied可以先执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519把私钥加到 ssh-agent 里再重试连接。4.4 日常使用 Git 的几个顺手配置配置类的东西我再说一个提高效率的全局忽略文件。不需要每个仓库都写一遍 .gitignore在用户级配置一次对所有仓库生效。创建全局忽略文件git config --global core.excludesfile ~/.gitignore_global然后在 ~/.gitignore_global 里写入常见的忽略内容.DS_Store *.log *.swp .idea/ .vscode/ node_modules/macOS 用户最该防的就是 .DS_Store这个文件是 Finder 自动生成的一不小心就进了 Git 提交很烦人。写了全局忽略之后至少不会再因为 .DS_Store 污染仓库了。另外如果不习惯每次 push 都输账号密码可以启用 Git 的凭据存储git config --global credential.helper osxkeychainmacOS 下 Git 会调用 Keychain 保存凭据第一次输入后以后就不用再输了。5. 真实踩坑记录常见报错与解决办法5.1 curl 报错、安装脚本无法下载症状执行官方安装命令时提示 curl: (7) Failed to connect 或 curl: (28) Operation timed out。原因脚本要访问 raw.githubusercontent.com这个域名在部分网络环境下连接不稳定。跟你的姿势没关系纯粹是线路问题。解决策略优先用浏览器或者其他方式把 install.sh 下载到本地然后本地执行。或者把安装脚本放到镜像站托管的路径下不过不同镜像站的脚本路径有差异用本地执行最省心。执行时把前面的 export 变量全部设置好脚本会自动走镜像拉仓库。5.2 安装时提示权限不足、无法创建目录症状安装进行到一半提示 mkdir /opt/homebrew 失败或者 Permission denied。原因Homebrew 默认安装目录不在普通用户可写范围内脚本创建目录时需要权限但当前用户对 /opt 没有写权限。解决策略先手动创建目录并更改所有者sudo mkdir -p /opt/homebrew sudo chown -R $(whoami):admin /opt/homebrew执行完再重新运行安装脚本。注意之后不要用 sudo brew install 来绕过权限问题。brew 本身不希望以 root 身份运行用 sudo 会带来一堆文件所有者错乱的问题比权限不足还难处理。5.3 brew update 一直卡住或者报 unable to access症状执行 brew update 后长时间停留在 Updating没有任何进度或者直接提示 fatal: unable to access https://github.com/...。原因git fetch 远程仓库时连接 GitHub 失败常见于刚装完没换源的状态。解决策略按第 3 节的方法把三个仓库 remote 地址换成镜像源然后重开终端再执行 brew update。如果已经换过源还是卡检查 HOMEBREW_BOTTLE_DOMAIN 是否写错或者镜像站临时同步异常换一个镜像源即可。5.4 git clone 慢、断线、卡住症状git clone 大型仓库时速度极慢甚至中途报错。解决策略如果是大仓库用浅克隆快速拉取git clone --depth1 https://github.com/xxx/xxx.git这样只克隆最新版本不下载完整历史体积能小一个量级。如果后续需要完整历史再执行 git fetch --unshallow 补全。另外对国内托管平台上的项目可以直接用平台自身的加速链路比如 Gitee 镜像对 GitHub 上的知名开源项目也可以搜一下国内镜像仓库clone 回来再改 remote。还有一种情况Git 默认使用 HTTP/2 连接部分网络环境对 HTTP/2 兼容性一般可以尝试强制使用 HTTP/1.1git config --global http.version HTTP/1.1这只是让 Git 走更老的协议兼容性更好对某些网络环境确实有奇效。5.5 brew install --cask 安装 GUI 应用卡住症状安装 GUI 应用时长时间停在 Downloading或者网速很慢。原因cask 应用安装时元数据从 homebrew-cask 仓库读取但真正的安装包通常从应用官网或其他 CDN 下载这部分流量不经过 bottle 镜像所以换源解决不了所有下载慢的问题。解决策略大文件安装包可以用下载工具先下载到本地再用 brew install --cask 指向本地文件安装。或者耐心等待部分大应用下载几百 MB 需要时间看起来像是卡住实际还在跑。5.6 卸载 Homebrew 时清理不干净如果你已经折腾到想卸载重装记住一个要点Homebrew 的安装目录不只在 /opt/homebrew还有用户目录下的缓存、日志和配置残留。官方卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)跑完之后手动清理这些路径/opt/homebrew ~/Library/Caches/Homebrew ~/Library/Logs/Homebrew ~/Library/LaunchAgents/homebrew.mxcl.plist再把 ~/.zshrc 里和 Homebrew 相关的 export 与 PATH 配置删掉。重装之前清理干净能避免很多医学上叫不出名字的玄学报错。最后说一点个人体会。配置环境这件事速度远没有稳定性重要。很多刚接触 Mac 的朋友喜欢在网上找各种 “一键脚本”今天试一个明天试一个结果装出来一堆乱七八糟的环境变量反而是后续所有问题的根源。我自己更倾向于走官方脚本加镜像变量的路子每一步都验证一下出了问题知道去哪排查。按照上面这套流程走下来从拿到新机器到 Homebrew 和 Git 全部可用慢的话半小时内也搞定了。剩下的时间安心去写代码比什么都强。