如果你在 Mac 上写过两年代码或者只是频繁折腾软件应该绕不开 brew 这个名字。它是 macOS 上最主流的软件包管理工具官方名字叫 Homebrew平时大家直接叫 brew。简单说brew 就像一个“应用商店”不过它面向的不是手机 App而是命令行工具和开发环境git、python、mysql、nginx、openjdk一条命令就能装好升级和卸载也由它统一接管。这篇文章就以“Mac 安装 brew”为主线把从零到能正常使用再到后续常见报错如何排查的完整流程讲清楚。不管你是刚换 Mac 的新手还是已经装了但经常遇到坑的老用户都可以对照着操作。1. 为什么 macOS 需要 brew包管理器解决了什么问题1.1 没有 brew 的“原始时代”在 brew 出现之前在 Mac 上装开发工具是比较痛苦的。以装个 Python 为例正常路径是打开浏览器、搜索官网、下载 pkg 安装包、双击安装、填管理员密码装完之后还要自己处理 PATH。想升级把旧版删掉再下载新版重来一遍。更麻烦的是依赖装 A 软件之前要先装 B 库B 库又依赖 C手动管理这些关系很容易把系统环境搞乱。brew 把这一整套流程变成了“包管理器”的标准模式。它把软件打包成了一个个 formula命令行工具和 cask图形应用并记录它们的依赖关系。你执行 brew install python 时它会自动把 python 的编译依赖、运行库也一并处理掉。装完之后升级用 brew upgrade python卸载用 brew uninstall python所有东西都在一个可追踪的清单里。这种体验和 iPhone 上从 App Store 装应用很接近区别是 brew 帮你同时管了“底层依赖”和“应用本体”。我用了 brew 大概八九年换过几台 Mac每次新机器到手第一步都是先把 brew 装上再通过它批量装回自己惯用的工具。这个过程非常省心也几乎是 macOS 开发者的默认起手式。所以第一步理解 brew 是什么比急着跑安装命令更重要。1.2 brew 的本体brew、cask、services 如何各司其职brew 这个词有时候指整个 Homebrew 工具链但它实际包含三个相对独立的部分。最核心的是 brew 本体负责安装和卸载命令行工具Homebrew Cask 负责安装带图形界面的应用比如 Chrome、VS Code、iTerm2命令是 brew install --cask 应用名Homebrew Services 负责管理后台服务比如装完 nginx 或 mysql 之后可以用 brew services start nginx 让它在后台持续运行。这三块的安装目录也不一样。命令行工具默认装进 Homebrew 的前缀目录Apple Silicon 机器上是 /opt/homebrewIntel 机器上是 /usr/localCask 安装的图形应用大部分会进 /Applicationsservices 则统一管理那些需要常驻的后台进程。理解这个结构后面遇到“文件跑哪里去了”“为什么 brew list 里看不到某个软件”这类问题就能很快定位。对于刚接触 brew 的人来说暂时不需要记太多只用知道装命令行工具用 brew install装图形应用加 --cask管后台服务用 brew services。三个命令覆盖了 90% 的使用场景。2. 安装前的准备工作先搞清芯片、系统和依赖2.1 确认 Mac 芯片架构与系统版本安装 brew 之前先花十几秒认清自己这台机器的底细能省掉后面一大堆弯路。第一个关键信息是芯片架构。点击屏幕左上角苹果图标选择“关于本机”这里能看到芯片一栏——如果写着 Apple M1、M2、M3 这类那就是 Apple Silicon如果写着 Intel Core i5/i7那是 Intel 机型。更准确的办法是打开终端执行 uname -mApple Silicon 会输出 arm64Intel 输出 x86_64。第二个信息是系统版本终端执行 sw_vers 就能看到。Homebrew 对 macOS 版本有最低要求当前版本一般要求 macOS 14 或更高具体以官方仓库说明为准较早的系统虽然也能装上旧版 brew但后续软件源和预编译包都会受限。如果你在“关于本机”里看到系统已经很老建议优先考虑升级系统而不是强行装新版本 brew。为什么芯片架构这么重要因为 Homebrew 按架构区分安装路径和预编译包。Apple Silicon 上公式默认装在 /opt/homebrewIntel 上装在 /usr/local。如果你在 M 系列芯片上误用了为 Intel 准备的安装方式后面极容易遇到路径找不到、二进制版本不对、运行报错等一系列问题。2.2 提前安装 Xcode Command Line ToolsHomebrew 的安装脚本在正式安装前会先检查系统里是否已经装了 Xcode Command Line Tools命令行开发者工具。这套工具包含 git、clang 编译器、make 等基础组件brew 本身和很多 formula 的编译过程都依赖它。好消息是你不需要为此安装完整的 Xcode那是个好几个 G 的大块头只装命令行工具就够了。方法很简单打开终端输入 xcode-select --install系统会弹出一个安装窗口点击“安装”然后等它下载完成即可。这个过程一般几分钟取决于网络速度。安装完可以执行 xcode-select -p 验证能看到 /Library/Developer/CommandLineTools 这类路径就说明没问题。有时候你之前装过 Xcode 或命令行工具再执行 xcode-select --install 会提示“command line tools are already installed”那就直接跳过。还有个小细节如果系统提示找不到 git通常是命令行开发者工具不完整重新跑一次 xcode-select --install 往往能解决。2.3 账号权限、用户目录与磁盘规划brew 的官方安装脚本在部分场景下会需要管理员权限所以安装前确认你的当前账号是管理员账号并且记得登录密码。执行命令时一旦提示 sudo 请输入密码输入即可。如果当前是普通用户账号先去“系统设置-用户与群组”里确认权限避免装到一半权限不足。另外有个比较隐蔽的坑如果用户的个人目录放在外部磁盘或者网络磁盘上brew 安装脚本会给出警告某些依赖的编译过程也容易出错。最稳妥的做法是把用户主目录放在 Mac 内置硬盘上再执行安装。还有就是留意磁盘剩余空间brew 本体加上命令行工具占用并不大但如果接下来要装很多软件留出几十 G 的可用空间会比较从容。这些都是我踩过的细节问题。曾经有一次因为用户目录挂在外置硬盘上brew 装 git 时编译步骤反复失败折腾了半小时最后把目录迁回内置盘一次通过。所以别小看安装前的准备很多时候报错与 brew 本身无关环境问题才是大头。3. 执行安装官方脚本与镜像源加速3.1 官方脚本安装的标准姿势安装 brew 的方式有不少官方推荐的是直接执行远程脚本。在终端里粘贴下面这行命令然后回车/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这个脚本会做几件事检查系统版本和芯片架构再次检查命令行工具是否就绪把你当前登录的普通用户目录归为 brew 目录的所有者然后从 GitHub 拉取 brew 本体仓库再下载必要的初始组件。整个过程会在终端里滚动输出大量日志结尾出现 “Installation successful” 就说明装好了。需要说明的是curl 后面的 -fsSL 参数含义是失败时报错、遇到 HTTP 错误不输出、静默跟随跳转。如果断网或者网络不稳定你会直接看到 curl 报错而不会拿到一个半截安装。这种设计对用户是友好的发现问题可以立刻重来。官方脚本默认的下载地址是 GitHub。如果当前网络访问 GitHub 比较顺畅整个过程通常会非常快如果网络环境一般下载 brew 本体和后续更新仓库时容易卡住。这也就是为什么后面要单独讲镜像源的原因。3.2 网络慢的解法环境变量换镜像源不少同学的 brew 安装失败其实不是命令写错而是从 GitHub 下载资源太慢或者连接直接被重置。这里最常用的解法是在跑官方脚本之前先把下载地址换成开源镜像站。brew 提供了环境变量来覆盖默认连接地址其中最常用的有四个HOMEBREW_BREW_GIT_REMOTE 控制 brew 本体仓库HOMEBREW_CORE_GIT_REMOTE 控制核心 formula 仓库HOMEBREW_API_DOMAIN 控制 JSON API 接口HOMEBREW_BOTTLE_DOMAIN 控制预编译包bottle的下载地址。以中科大开源镜像站为例打开终端执行以下命令再跑官方安装脚本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 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)实测下来在 GitHub 直连很慢的网络下这种方式能把安装时间从几十分钟压缩到几分钟。值得提醒一句镜像站的地址会不定期调整比如清华、中科大、阿里云的路径格式并不完全一样每次安装前先去镜像站官网看一眼最新的路径是最稳的做法。还要注意这些 export 只是对当前终端窗口生效。如果你开了一个新窗口环境变量就不存在了所以要么每次在同一个窗口里安装要么把 export 写进 shell 配置文件.zshrc 或 .bash_profile。后面讲安装完成后的持续换源时我会再给一个更规范的做法。3.3 安装要花多久时间预期与进度判断经常看到有人问“macOS 安装 brew 要多久”。这个问题很难给出一个统一数字因为主要瓶颈不在计算而在网络。如果直连 GitHub 且速度不错完整安装 brew 本体大概 3 到 10 分钟如果网络一般可能要二三十分钟如果卡在一个下载点长时间不动基本就是网络问题赶紧换方案不要死等。安装过程中你会看到很多输出比如 “ Tapping homebrew/core” 和 “Cloning into” 等字样。如果一个阶段停留超过十分钟没有任何变化建议直接 CtrlC 中断检查网络或切换镜像源后重试。死等不会等来结果尽早换路才高效。另外第一次安装后通常会自动执行 brew update把本地索引更新到最新。这一步同样受网络影响。如果你只想先把 brew 装好可以在环境变量里加入 HOMEBREW_NO_AUTO_UPDATE1暂时关闭自动更新等装好后再手动决定是否更新。4. 安装完成后的收尾PATH、验证与换源4.1 把 brew 写进 shell 环境变量安装脚本结束后终端末尾会给出两行“Next steps”提示告诉你还需要执行类似下面的命令把 brew 的可执行文件路径加进 shell 环境变量。这一步如果跳过下次新开终端会提示 command not found: brew很多人就在这里卡住了。Apple Silicon 芯片执行echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 芯片执行echo eval $(/usr/local/bin/brew shellenv) ~/.zprofile eval $(/usr/local/bin/brew shellenv)简单解释下原理brew 的安装目录不在系统默认的 PATH 里系统找不到 brew 命令。第一条命令把一个初始化语句写进当前用户的 .zprofile 文件这样每次打开新的 zsh 终端都会自动加载这个路径第二条命令让当前终端立刻生效不用重启终端。如果你用的是 bash 而非 zsh把目标文件从 .zprofile 改成 .bash_profile或 .zshrc 对应调整也可以。验证是否配置成功新开一个终端窗口执行 which brew能看到 /opt/homebrew/bin/brew 或者 /usr/local/bin/brew 就算成功。4.2 brew doctor 和 brew config 自检装完 brew、配好 PATH 之后我强烈建议先跑一次自检。执行 brew doctor它会扫描整个环境指出可能影响 brew 使用的问题。常见提示包括命令行工具版本异常、某些目录权限不对、环境变量冲突等绝大多数警告都有具体修复建议照着提示执行即可。看到 “Your system is ready to brew” 就说明一切正常。再执行 brew config可以查看 brew 的详细配置信息。重点关注这几项HOMEBREW_PREFIX 是安装前缀HOMEBREW_CELLAR 是软件安装目录HOMEBREW_BOTTLE_DOMAIN 是预编译包下载域名。如果你刚才设置了镜像源这里能看到对应的镜像地址确认配置生效。这两条命令不是可有可无的形式主义。很多初次安装成功但后续使用报错的用户问题往往出在环境不自检这一步。比如 PATH 里同时存在多个版本的 python 或 gitbrew 装好的工具能不能被正确调用brew doctor 会给出非常直接的建议。4.3 安装后的持久换源与常见坑安装过程中通过 export 设置镜像环境变量只对当前终端生效。如果希望以后每次使用 brew 都默认走镜像源可以把 export 语句写进 shell 配置文件的末尾。以 zsh 为例echo export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api ~/.zprofile echo export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles ~/.zprofilebrew 本体仓库和 core 仓库也可以用 git remote 直接改。使用中科大镜像时git -C $(brew --repo) remote set-url origin https://mirrors.ustc.edu.cn/brew.git git -C $(brew --repo homebrew/core) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git需要留意的是新版 brew 的 formula 索引主要通过 JSON API 获取所以 HOMEBREW_API_DOMAIN 和 HOMEBREW_BOTTLE_DOMAIN 这两个变量更重要core 仓库的 remote 在部分版本里甚至可以不同步保持默认即可。如果误改了 remote想恢复官方地址把 remote set-url 里的地址换成 https://github.com/Homebrew/brew.git 和 https://github.com/Homebrew/homebrew-core.git 就行。还有一个常见的坑换源之后如果 brew update 还是卡住多半是之前“半成品”的 git 仓库状态不对。这时候进到仓库目录比如 cd $(brew --repo)执行 git status 看看状态必要时先把仓库备份再删掉重新 clone效果比反复重试好很多。5. 高频报错与排查技巧实录5.1 网络类错误curl、443、Connection refused安装 brew 最常遇到的报错就是网络层失败。我看到最多的一种是curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused这行的含义是 curl 尝试连接 raw.githubusercontent.com 的 443 端口失败。在多数情况下brew 安装脚本都需要从 GitHub 服务器拉取脚本或仓库网络连通性不佳时就会出现这类错误。处理办法很简单先确认网络能正常访问网页然后按前面讲的方式设置镜像源环境变量重新执行安装脚本或者换一个网络环境再试。另一种常见报错是 “RPC failed; curl 56 OpenSSL SSL_read: Connection was reset, errno 54”一般出现在 clone brew 仓库的过程中。这种情况说明连接在传输阶段被中断解决办法同样是换镜像源、重试。GitHub 仓库因为传输文件多、连接容易中断镜像站做了一层中转失败概率会明显降低。有同学会反复试同一个方案在一片区域反复“撞墙”。这时候请跳出“再试一次”的思维直接切镜像源安装效率高得多。5.2 权限类错误目录不可写、Operation not permitted权限类报错是另一个高频问题。在 Intel Mac 上brew 默认前缀是 /usr/local而这个目录经常被系统强制保护或者被之前手动安装的软件占用。执行安装脚本或 brew install 时可能看到 Permission denied 或者 Operation not permitted。一个常见修法是把目录所有权交给当前用户sudo mkdir -p /usr/local sudo chown -R $(whoami) /usr/localApple Silicon 上一般不需要处理 /usr/local 的权限因为 brew 默认装在自己的 /opt/homebrew 目录里这个目录安装脚本会自行创建并授权。如果在 Apple Silicon 上仍然遇到 /usr/local 相关问题大多是之前手动创建的残留目录导致确认没有重要文件后可以谨慎处理。需要特别提醒不推荐用 sudo chown -R 去改整个系统目录的属主也不要随意 chmod 777。这会把系统文件权限搞得一团糟后续可能出现更奇怪的问题。改权限的原则是“最小范围修复”只处理 brew 需要写入的目录。5.3 brew update 卡住的几种解法brew update 卡住是装完后的日常问题。现象通常是执行 brew update 后长时间没有输出或者一直停在某个 “Cloning” 阶段。原因大多是本地 git 仓库连接远端失败。解法有三个从轻到重排列。第一临时关闭自动更新使用 HOMEBREW_NO_AUTO_UPDATE1 brew install 包名先保证安装能用。第二切换镜像 remote让 update 从镜像仓库拉取索引和前面讲到的持久换源一致。第三如果本地仓库状态已经混乱可以进入 brew 仓库目录brew --repo手动执行 git fetch 看具体报错或者备份后删除仓库重新 clone。删除仓库不会影响已安装的软件只是索引重新下载一次。我的建议是平时把镜像源配置好brew update 基本不会再让你操心。每次执行 install 时brew 默认会检查自动更新这个检查在镜像源配置不当的情况下会变成等待的“黑洞”。很多用户觉得 brew 卡其实是卡在自动更新上。熟悉后可以显式设置 HOMEBREW_NO_AUTO_UPDATE1再配合定期手动 brew update体验会顺畅许多。5.4 版本冲突新装的工具调不起来装完新工具却执行不了是新手最容易懵的场景。比如系统自带 git 是 2.39但你 brew install git 装了 2.47执行 git --version 还是 2.39。原因很简单系统自带的 git 路径在 /usr/bin/gitbrew 装的在 /opt/homebrew/bin/git而 PATH 变量里的搜索顺序是前者更靠前。解决办法是调整 PATH 顺序让 brew 目录排在更前面。如果你已经在 .zprofile 里写了 eval $(/opt/homebrew/bin/brew shellenv)系统一般会自动把 /opt/homebrew/bin 放到 PATH 靠前位置。验证方式执行 which git看是否指向 /opt/homebrew/bin/git如果不是检查 .zprofile 是否被正确加载或者手动在 .zshrc 里把 /opt/homebrew/bin 追加到 PATH 前面。类似的冲突也会出现在 python、openssl 等工具上。这不算 bug而是环境管理的一部分。理解 PATH 机制之后你就能快速定位“为什么执行的可执行文件不是我以为的那个”。6. 从安装到日常用常用命令与实战场景6.1 高频命令速查表装好 brew 之后日常使用其实就下面这些命令操作命令搜索软件包brew search 关键字查看软件信息brew info 包名安装命令行工具brew install 包名安装图形应用brew install --cask 应用名卸载软件brew uninstall 包名查看已安装brew list更新 brew 本身brew update升级所有软件brew upgrade查看需要升级brew outdated清理旧版本brew cleanup管理后台服务brew services list/start/stop 服务名这些命令不用死记用多了自然熟。我通常会把 brew update 和 brew upgrade 放在一起说因为 brew upgrade 升级的是已安装的软件包brew update 更新的是索引本身两者配合使用才能保证升级到最新版本。6.2 常见开发工具安装实例举几个实际安装例子感受一下 brew 的效率。装 python 和 gitbrew install git python装 JDKOpenJDK 17brew install openjdk17装 MySQL 数据库并注册为后台服务brew install mysql brew services start mysql装 Maven、Node.jsbrew install maven node以上命令的下载和安装过程都是自动的。如果你之前配置好了镜像源速度会非常可观。我个人的习惯是先把 brew 装好然后一条命令把 git、python、node、openjdk 这些基础环境全部装完整个过程不超过十分钟。对于经常接触新工具的人来说brew 还能帮你快速安装 jq、wget、tree、ripgrep 这类小而美的命令行工具用 brew search 搜一下就能找到。除了命令行工具图形应用也可以通过 cask 安装。比如brew install --cask iterm2 brew install --cask visual-studio-code brew install --cask google-chromecask 会把应用安装到 /Applications 目录和从官网下载拖入的效果一致但好处是版本可追踪、更新更方便。6.3 卸载与清理给硬盘留点空间brew 装得越多对磁盘空间的占用也越大尤其是老版本残留和编译中间产物。定期清理是保持环境健康的一部分。先看哪些包可以升级brew outdated然后升级brew upgrade卸载无用包brew uninstall 包名清理不再需要的依赖brew autoremove清理旧版本和临时文件brew cleanup。执行 brew cleanup 后系统会删掉每个软件包的老版本文件只保留当前版本。如果磁盘吃紧这招通常能腾出不少空间。如果你彻底不想用 brew 了官方也提供了卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)卸载脚本会询问你要删除哪些目录确认后会把 brew 本体、仓库和由 brew 管理的软件目录一并清理。它会保留你手动安装的文件但由 brew 管理的软件会消失所以卸载前先想清楚不要把重要数据放在这些目录里。以我这些年的使用体验brew 装上只是开始真正让它发挥价值的是把你重复的操作沉淀成一条条命令。刚装完的新机器环境整洁、镜像源配好之后维护起来会省很多精力。还有一些小习惯值得培养比如不要把 brew 目录的权限随意改大也不要因为一次慢就反复重装。很多问题不是 brew 的锅是网络和环境的问题。先检查连接再考虑换源基本能覆盖九成以上的麻烦。最后分享一个我自己的习惯每次在新 Mac 上装完 brew第一件事不是装各种软件而是先执行 brew doctor 确认环境干净再把镜像源配置写进 shell 配置文件。之后再去 brew install 并顺手保存一份常用软件清单方便以后重装机器直接批量恢复。这个方法我用了很多年身边的朋友照着做之后基本没有再被 brew 安装问题困扰过。