概述

Homebrew（简称 brew）是 macOS（及 Linux）上最流行的开源包管理器，用 Ruby 编写。它通过 formula（公式）定义软件包的构建规则，自动下载源码或预编译的 bottle（二进制包），安装到独立的 Cellar 目录，再 symlink 到统一的 prefix 下供系统全局使用。

核心概念速览

第一部分：行为图

用例图

展示 Homebrew 系统的三类角色及其核心用例。

活动图 — brew install 核心流程

展示从用户执行 brew install <formula> 到安装完成的完整决策与执行路径。

时序图 — brew install 完整交互

展示一次 brew install 中各组件之间的消息传递：CLI 解析、Homebrew Core 调度、下载策略、编译系统和链接器。

状态机图 — Formula 生命周期

展示一个 formula 从其初次提交 PR 到最终被移除的完整生命周期。

第二部分：结构图

包图 — 源码顶层模块

关键模块说明：

• bin/brew — 入口脚本，设置 Ruby 环境后加载 Library/brew.rb
• Library/Homebrew/cmd/ — 内置命令（install, uninstall, update, upgrade...）
• Library/Homebrew/dev-cmd/ — 开发命令（如 audit, bottle, create, test...）
• Library/Homebrew/os/ — 平台适配层（Mac / Linux），处理 OS 特定逻辑
• completions/ — bash/zsh/fish 自动补全
• manpages/ — man 手册页（Roff 格式）

组件图 — 生态系统架构

类图 — 核心领域模型

Demo 代码：最小 Formula

class Foo < Formula
  desc "A simple example formula"
  homepage "https://example.com"
  url "https://example.com/foo-1.0.tar.gz"
  sha256 "abc123..."
  license "MIT"
  version "1.0"

  depends_on "cmake" => :build

  def install
    system "cmake", "-S", ".", "-B", "build", *std_cmake_args
    system "cmake", "--build", "build"
    system "cmake", "--install", "build"
  end

  test do
    system "#{bin}/foo", "--version"
  end
end

部署图 — 文件系统布局

第三部分：使用手册

安装

# macOS / Linux 官方安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装后添加到 PATH (macOS ARM)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# 验证
brew doctor

核心命令

软件包管理

brew install <formula>       # 安装 formula（默认使用 bottle）
brew install --cask <cask>   # 安装 GUI 应用 (cask)
brew uninstall <formula>     # 卸载
brew reinstall <formula>     # 重新安装
brew upgrade [formula]        # 升级所有 / 指定软件
brew pin <formula>           # 锁定版本，阻止升级
brew unpin <formula>         # 解锁
brew autoremove               # 移除不再需要的自动依赖
brew cleanup                  # 清理旧版本和缓存
brew list                     # 列出已安装的所有 formula
brew list --cask              # 列出已安装的所有 cask
brew leaves                   # 列出未被其他包依赖的顶层包

信息查询

brew search <keyword>        # 搜索 formula/cask
brew info <formula>          # 查看详细信息
brew info --json=v2 <f>      # JSON 格式输出
brew deps <formula>          # 查看依赖
brew deps --tree <formula>   # 树状依赖图
brew desc <formula>          # 查看描述
brew home <formula>          # 在浏览器打开主页
brew outdated                 # 列出有更新的包

系统维护

brew update                   # 更新 Homebrew 自身及 tap
brew doctor                   # 诊断系统问题
brew config                   # 查看系统配置
brew --version                # 查看版本
brew analytics off            # 关闭匿名统计

服务管理 (brew services)

brew services start <f>      # 启动服务并注册自启
brew services stop <f>       # 停止服务并取消自启
brew services restart <f>    # 重启服务
brew services list            # 列出所有服务状态
brew services info <f>       # 查看服务详情

Brewfile — 声明式环境管理

brew bundle dump              # 导出当前安装到 Brewfile
brew bundle install           # 从 Brewfile 安装所有依赖
brew bundle check             # 检查是否全部安装
brew bundle cleanup           # 卸载 Brewfile 中未列出的包

Brewfile 示例：

tap "homebrew/cask"
tap "user/tap"

brew "node"
brew "python@3.12"
brew "git"
brew "ffmpeg", restart_service: true

cask "google-chrome"
cask "visual-studio-code"

mas "Xcode", id: 497799835

vscode "golang.go"
vscode "ms-python.python"

服务管理原理（brew services 与 launchd）

一句话结论：brew services 只是 Homebrew 对 macOS launchd 的封装，真正调度、守护进程的是 launchd。

工作原理分三步：

1. 生成 plist：brew services start <f> 把服务定义写成 homebrew.mxcl.<name>.plist，放到 ~/Library/LaunchAgents/（用户级）或 /Library/LaunchAgents/（系统级）
2. 注册到 launchd：通过 launchctl bootstrap（旧版 load）把该 plist 加载给 launchd
3. launchd 接管守护：按 plist 里的 RunAtLoad（加载/开机时启动）、KeepAlive（进程退出后自动重启）等策略拉起并保活进程

本机 mysql@8.0 的真实 plist（~/Library/LaunchAgents/homebrew.mxcl.mysql@8.0.plist）：

<dict>
  <key>KeepAlive</key>
  <true/>                                     <!-- 进程退出后自动重启 -->
  <key>Label</key>
  <string>homebrew.mxcl.mysql@8.0</string>    <!-- launchd 中的唯一标识 -->
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/opt/mysql@8.0/bin/mysqld_safe</string>
    <string>--datadir=/opt/homebrew/var/mysql</string>
  </array>
  <key>RunAtLoad</key>
  <true/>                                     <!-- 加载时即启动（含开机） -->
  <key>WorkingDirectory</key>
  <string>/opt/homebrew/var/mysql</string>
</dict>

命令对照

常用环境变量

Tap 与扩展

Tap 是第三方 formula/cask 的 Git 仓库。命名约定：homebrew-<name>。

brew tap                      # 列出已安装的 tap
brew tap user/repo           # 添加 tap (映射到 github.com/user/homebrew-repo)
brew untap user/repo         # 移除 tap
brew tap --repair            # 修复 broken tap

外部命令：放在任何 PATH 上名为 brew-<cmd> 的可执行文件，或 tap 的 cmd/ 目录中的 Ruby 文件，均可作为 brew <cmd> 调用。

核心 Tap 仓库