Homebrew 使用指南
Homebrew 的诞生背景
刚接触 macOS 时，安装软件似乎并不复杂：打开浏览器、进入官网、下载 DMG 文件，再把应用拖进“应用程序”目录即可。
但当我们开始搭建开发环境，事情很快就会变得麻烦。Git、Node.js、wget、Redis 等工具来自不同的网站，各自有不同的安装方式；软件升级后，旧版本和配置文件也可能散落在系统的不同位置。换一台 Mac，又要把这套流程重新走一遍。
Linux 很早就有 apt、yum 等包管理器，可以用一条命令完成软件的搜索、安装、升级和卸载。macOS 虽然也有 MacPorts、Fink 等工具，却没有一个由系统提供、面向开源软件的统一包管理器。
Homebrew 正是在这样的背景下出现的。它最初由 Max Howell 创建，希望用一套简单的命令管理 macOS 缺少的软件。它没有把文件随意塞进系统目录，而是把每个软件安装到独立位置，再通过软链接把可执行文件放进统一的搜索路径。
这也是名字中 “Homebrew” 的含义：像在家酿啤酒一样，用自己的方式为 Mac 补齐需要的工具。它的主命令 brew，也一直沿用了这套啤酒主题。
Homebrew 是什么
Homebrew 是一个开源的包管理器。对使用者来说，它最直接的价值是把寻找安装包、处理依赖、配置路径、检查更新和卸载软件这些操作，统一成一组 brew 命令。
例如，安装 wget 只需要执行：
1 | brew install wget |
安装 Visual Studio Code 也只需要一条命令：
1 | brew install --cask visual-studio-code |
在继续使用之前，可以先认识四个经常出现的概念：
- Formula：软件的安装配方，主要用于命令行工具、开发库和后台服务，例如 wget、Git、Redis。
- Cask：主要用于安装带有图形界面的 macOS 应用，例如 Visual Studio Code、Firefox。
- Bottle：Homebrew 预先构建好的二进制包。使用 Bottle 可以省去本地编译的时间。
- Tap：软件配方的来源，可以理解为额外的软件仓库。Homebrew 有官方仓库，软件开发者和其他用户也可以维护第三方 Tap。
Homebrew 会把 Formula 安装到自己的 Cellar 中，再将需要使用的文件链接到 Homebrew 的安装目录。Apple Silicon Mac 默认安装在 /opt/homebrew，Intel Mac 默认安装在 /usr/local。使用默认目录，通常才能直接使用官方提供的 Bottle。
安装 Homebrew
安装前，建议先打开“终端”，安装或确认 Xcode Command Line Tools：
1 | xcode-select --install |
如果系统提示已经安装，可以直接进行下一步。
从 Homebrew 官网 复制安装命令并执行：
1 | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
这条命令会先下载安装脚本，然后交给 Bash 执行。脚本在真正修改系统前会说明准备进行的操作，并等待用户确认。安装过程中可能会要求输入当前账户的密码，这是为了创建安装目录等必要操作；输入密码时终端不会显示字符，正常输入并按回车即可。
安装结束后，不要急着关闭终端。安装程序通常会在 Next steps 中给出配置环境变量的命令，应优先复制并执行它提供的内容。
Apple Silicon Mac 通常需要执行：
1 | echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile |
Intel Mac 对应的路径通常是 /usr/local/bin/brew：
1 | echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile |
brew shellenv 会把 Homebrew 需要的路径加入当前 Shell 环境。第一条命令将配置写入 ~/.zprofile，保证以后打开终端时仍然生效；第二条命令让配置立即在当前终端生效。
最后检查安装结果：
1 | brew --version |
brew --prefix 可以确认当前 Homebrew 的安装位置；brew doctor 会检查环境并给出建议。看到 Warning 不一定代表 Homebrew 无法使用，应先阅读具体内容，再判断是否需要处理。
安装第一个软件
假设现在需要安装 wget。与其先去搜索引擎寻找安装包，不如直接让 Homebrew 搜索：
1 | brew search wget |
安装前可以查看软件版本、依赖、主页等信息：
1 | brew info wget |
确认无误后进行安装：
1 | brew install wget |
安装结束后验证是否可用：
1 | wget --version |
命令行工具之外，Homebrew 也能管理图形应用。例如安装 Visual Studio Code：
1 | brew search visual-studio-code |
Homebrew 会下载应用并把它安装到 macOS 的“应用程序”目录。以后迁移到新 Mac 时，就不必再逐个打开官网下载安装包了。
查看已经安装的 Formula 和 Cask，可以分别执行：
1 | brew list --formula |
常用操作
日常使用 Homebrew，最容易混淆的是更新 Homebrew 和升级软件。
1 | 更新 Homebrew 自身以及可用软件的信息 |
brew update 更新的是 Homebrew 的数据，不等于升级已经安装的软件。执行全量 brew upgrade 前，最好先通过 brew outdated 查看清单，确认新版本不会影响正在使用的开发环境。
软件出现异常时，可以尝试重新安装：
1 | brew reinstall wget |
不再需要的软件可以卸载：
1 | brew uninstall wget |
Homebrew 会保留一部分旧版本和下载缓存。可以先预览待清理内容，再执行清理：
1 | brew cleanup --dry-run |
如果想了解软件之间的依赖关系，可以使用：
1 | 查看某个软件依赖了什么 |
遇到问题时，下面几个命令通常比直接删除目录更有帮助：
1 | brew config |
其中 brew config 会输出 Homebrew、macOS、CPU 架构和开发工具等环境信息，适合在排查问题时留存。
管理后台服务
Redis、MySQL、PostgreSQL 这类软件除了需要安装，还需要启动后台进程。Homebrew 可以通过 brew services 统一管理它们。
以 Redis 为例：
1 | brew install redis |
不带 sudo 执行 brew services start 时，Homebrew 会为当前用户启动服务，并注册为登录后自动启动。
常用的服务管理命令如下：
1 | 查看服务状态 |
如果只是本地开发，通常使用当前用户级别的服务就够了，不需要加 sudo 把它注册成系统级服务。
备份软件清单
Homebrew 解决了“如何安装软件”，Brewfile 则进一步解决了“如何在另一台 Mac 上装回同一批软件”。
一个简单的 Brewfile 可能是这样：
1 | brew "wget" |
在包含这个文件的目录中执行下面的命令，Homebrew 就会安装其中缺少的软件，并按默认行为升级已经过期的项目：
1 | brew bundle |
如果只想补齐缺少的软件，不希望同时升级已有项目，可以使用 brew bundle --no-upgrade。
如果当前 Mac 已经配置好了开发环境，可以生成一份软件清单：
1 | brew bundle dump --file="$HOME/Brewfile" --force |
换到新 Mac 后，安装 Homebrew，再恢复这份清单：
1 | brew bundle --file="$HOME/Brewfile" |
建议把 Brewfile 放进个人配置仓库进行版本管理。这样记录下来的不再是一篇“新电脑要安装什么”的备忘录，而是一份可以重复执行的环境配置。
网络不畅怎么办
在国内网络环境下，Homebrew 偶尔会遇到下载缓慢或超时。排查时不要把所有问题都归结为“Homebrew 连不上”，因为一次安装可能会访问不同的地址：
- 安装脚本通常来自
raw.githubusercontent.com； - Formula 和 Cask 的元数据通常来自 Homebrew API；
- Bottle 通常从容器镜像服务下载；
- Cask 安装包还可能来自软件自己的官网。
先观察报错中的域名，可以更快判断究竟是哪一步失败。如果只是临时网络问题，可以重试，或者在当前终端设置本地代理：
1 | export HTTP_PROXY=http://127.0.0.1:7890 |
端口需要根据自己的代理工具调整。使用结束后可以取消：
1 | unset HTTP_PROXY HTTPS_PROXY |
如果长期使用镜像，Homebrew 提供了 HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN 等环境变量，用来指定 API 和 Bottle 的镜像地址。具体值应以镜像提供方的最新说明为准，不建议从多年前的文章中直接复制一整套 git remote set-url 命令。
原因是 Homebrew 获取软件信息和安装包的方式会随版本变化。镜像地址也可能停止维护，长期保留失效配置反而会让正常网络下的安装失败。修改前应记录原配置，出现异常时及时撤销，并回到官方地址验证。
使用时要注意什么
不要随意使用 sudo
Homebrew 的安装程序可能在初始化目录时请求管理员权限，但安装完成后，日常的 brew install、brew upgrade 和 brew uninstall 不需要加 sudo。
随意执行 sudo brew ... 可能产生属于 root 用户的文件，之后普通用户更新和卸载时就会遇到权限问题。除非清楚某条命令的系统级效果，否则不要使用 sudo。
不要把 upgrade 当成无风险操作
brew upgrade 会升级所有过期的软件及相关依赖。数据库、运行时或基础库跨版本升级后，可能与现有项目不兼容。
更稳妥的做法是先执行 brew outdated，再使用 brew upgrade <formula> 按需升级。重要项目还应通过版本管理工具、容器或项目自己的锁文件固定运行环境，而不是完全依赖 Homebrew 中的最新版本。
谨慎使用第三方 Tap
Tap 中的 Formula、Cask 和扩展命令并不只是静态下载地址，Homebrew 在处理它们时可能执行其中的 Ruby 代码。因此，添加第三方 Tap 前要确认仓库的维护者、来源和更新情况。
当前版本的 Homebrew 会区分官方 Tap 和需要明确授权的第三方内容。对于偶尔使用的软件，优先安装完整名称指向的具体项目，不要为了一个软件轻易信任整个仓库。
分清系统工具和项目依赖
Homebrew 适合安装 Git、Node.js、Python、Redis 等系统级工具，但不应替代项目自己的依赖管理方式。
例如，JavaScript 项目的依赖仍然应该记录在 package.json 和锁文件中；Python 项目应使用虚拟环境和对应的依赖文件。否则不同项目的依赖混在全局环境中，很容易出现“在我的电脑上可以运行”的问题。
不要直接修改 Homebrew 的目录
遇到链接或权限问题时，不要直接删除 /opt/homebrew、/usr/local 或 Cellar 中的文件，也不要根据不明来源的命令批量修改目录权限。
先通过下面的命令确认架构和真实路径：
1 | arch |
Apple Silicon Mac 如果从旧的 Intel Mac 迁移过数据，还可能同时存在 /usr/local 和 /opt/homebrew 两套 Homebrew。此时应先导出软件清单、确认当前终端使用的架构，再按照官方迁移建议处理，避免误删仍在使用的环境。
谨慎使用 cask 的 zap 参数
普通的 Cask 卸载以删除应用为主。如果需要进一步清理相关配置，可以使用：
1 | brew uninstall --cask --zap <软件名> |
但 --zap 可能删除应用之外的配置文件，甚至影响多个应用共享的文件。执行前应先确认这些数据是否还需要保留。
写在最后
Homebrew 最有价值的地方，不只是把一条很长的安装流程缩短成 brew install，而是给软件管理提供了一套一致的方式：先搜索和了解，再安装；需要时更新和卸载；最后用 Brewfile 把整个环境记录下来。
当换电脑或重装系统时，真正省时间的不是记住了多少条命令，而是能够把环境配置变成一份可以检查、修改和重复执行的清单。
本文涉及的命令会随 Homebrew 版本演进，安装和故障排查时应以官方资料为准：
