很多新 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，那就对不上了。

先确认当前 shell：

echo $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/homebrew，Intel 是 /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 好很多。

我整理了几个常用镜像源的信息，都是公共镜像，可以放心使用：

选哪个其实都可以，没必要纠结太久。我个人常用的习惯是：教育网环境优先清华，普通家庭宽带优先阿里云。如果你第一套镜像安装失败，换个源再试，不用死磕。

2.4 用镜像环境变量安装，一次到位

现在最稳妥的方式，不是去找网上的修改版安装脚本，而是先设置好环境变量，再运行官方原版安装脚本。Homebrew 官方在安装阶段支持通过环境变量覆盖仓库地址，这也是 2026 年主流镜像站文档里推荐的做法。

以清华源为例，打开终端，按顺序执行：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git" export HOMEBREW_BOTTLE_DOMAIN="https://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 brew

Apple Silicon 机器正常路径应该是 /opt/homebrew/bin/brew，Intel 机器是 /usr/local/bin/brew。如果 which 输出为空，手动把 PATH 写进 ~/.zshrc：

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

Intel 机器把 /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_DOMAIN="https://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_UPDATE=1 export HOMEBREW_NO_INSTALL_CLEANUP=1 export HOMEBREW_NO_ANALYTICS=1

HOMEBREW_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 auto

init.defaultBranch main 让新建仓库默认主分支叫 main 而不是 master，跟现在主流托管平台保持一致。pull.rebase false 保持默认的 merge 策略，适合不熟悉 rebase 的初学者。color.ui auto 让终端输出带上颜色，看 diff 和 status 会舒服很多。

查看所有全局配置：

git config --global --list

4.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 git@github.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 osxkeychain

macOS 下 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 --depth=1 https://github.com/xxx/xxx.git

这样只克隆最新版本，不下载完整历史，体积能小一个量级。如果后续需要完整历史，再执行 git fetch --unshallow 补全。另外，对国内托管平台上的项目，可以直接用平台自身的加速链路，比如 Gitee 镜像；对 GitHub 上的知名开源项目，也可以搜一下国内镜像仓库，clone 回来再改 remote。

还有一种情况：Git 默认使用 HTTP/2 连接，部分网络环境对 HTTP/2 兼容性一般，可以尝试强制使用 HTTP/1.1：

git 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 全部可用，慢的话半小时内也搞定了。剩下的时间，安心去写代码比什么都强。