Qiniu/technical/mac-dev-env-setup/homebrew-intro.md

---
tags: [homebrew, macos, package-manager]
create time: 2026-07-01 00:00
---

# Homebrew — macOS 包管理器

## 概述

Homebrew（简称 brew）是 macOS 上最流行的开源包管理工具，弥补了 macOS 缺乏官方包管理器的空白。它通过命令行安装、更新和卸载 Unix 工具和桌面应用，是 Mac 开发环境搭建的第一步。

## 核心概念

### 目录结构

```
/opt/homebrew/          # ARM Mac 安装根目录（M1/M2/M3/M4）
├── bin/                # 可执行文件（brew 本身在此）
├── Cellar/             # 已安装包的实际存放位置（版本化目录）
├── Cask/               # GUI 应用（--cask）的安装元数据
├── etc/                # 配置文件
├── include/            # C/C++ 头文件
├── lib/                # 动态链接库
├── opt/                # 当前活跃版本的 symlink 目标
├── share/              # 共享资源（man pages, completions 等）
└── var/                # 运行时数据

/usr/local/             # Intel Mac 安装根目录
```

> [!info] Cellar vs Opt
> `Cellar/<formula>/<version>` 存储每个版本的实际文件；`opt/<formula>` 是一个 symlink，始终指向当前最新版本。这就是 `brew upgrade` 后不需要重新配置 PATH 的原因。

### Formula vs Cask

| 类型 | 用途 | 示例 | 安装路径 |
|------|------|------|----------|
| **Formula** | CLI 工具和库 | `git`, `go`, `python@3.12` | `/opt/homebrew/Cellar/...` |
| **Cask** | GUI 桌面应用 | `visual-studio-code`, `iterm2` | `/Applications/` |

```bash
# Formula 安装
brew install git

# Cask 安装（注意 --cask 或直接用 install，brew v4+ 自动识别）
brew install --cask visual-studio-code
```

### Tap —— 第三方仓库

默认只包含 Homebrew 官方的 core tap（formula + cask）。社区维护的第三方仓库称为 **tap**。

```bash
# 查看已添加的 taps
brew taps

# 添加社区 tap
brew tap homebrew/cask-fonts    # 字体 cask
brew tap darwinports            # 假设的第三方 tap

# 从 tap 安装
brew install darwinports/my-tool
```

> [!tip] 常见社区 tap
> - `homebrew/cask-fonts` — 大量字体应用
> - `homebrew/core` 和 `homebrew/cask` 默认已添加
> - 添加前用 `brew search <name>` 确认是否在官方源中，避免不必要的 tap

## 代码示例

### 安装与初始化

```bash
# 一键安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# ARM Mac：将 brew 加入 shell profile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

`brew shellenv` 会输出需要注入到 shell 中的环境变量（PATH、MANPATH、CGO_CFLAGS 等），`eval` 将其应用到当前环境。

### 常用工作流

```bash
# 搜索包（formula + cask）
brew search neovim

# 查看详情（版本、依赖、安装数）
brew info neovim

# 安装
brew install neovim

# 指定版本（需先用 brew versions 或查 formula history）
brew install neovim@0.9

# 升级
brew upgrade                  # 升级所有可升级的包
brew upgrade neovim           # 只升级某个包

# 清理磁盘空间
brew cleanup                  # 删除旧版本缓存
brew cleanup --prune          # 同时清理孤立 symlink

# 诊断
brew doctor                   # 检查环境问题
brew config                   # 查看当前配置信息
```

### 管理依赖

```bash
# 查看某包的依赖树
brew deps --tree git

# 查看哪些包依赖某包（反向查询）
brew depends --tag python@3.12

# 列出已安装的包
brew list

# 列出可卸载的孤立依赖（无人引用）
brew autoremove
```

> [!warning] autoremove 不会删除你显式安装的包
> 只有那些因满足其他包的依赖而被自动安装、且当前不再被任何包需要的依赖才会被移除。

### 源码编译自定义参数

```bash
# 查看可用选项
brew options curl

# 安装时启用特定 flag
brew install curl --with-openssl

# 或者编辑 formula 后再安装（bottle 会被跳过）
brew edit curl     # 打开本地 formula 副本
brew install curl
```

`brew edit <formula>` 会在本地创建一个公式副本，适合临时修改编译参数，但升级时会提示冲突。

## 常见陷阱与最佳实践

### 1. PATH 优先级问题

macOS 系统自带的工具（如 `/usr/bin/python3`）可能比 brew 安装的更早出现在 PATH 中。确保 brew 路径在 `/usr/local/bin` 或 `/opt/homebrew/bin` 之前：

```bash
echo $PATH
# 期望顺序：/opt/homebrew/bin:...（在 /usr/bin 之前）
```

> [!tip] 验证方法
> 运行 `which git` 应输出 `/opt/homebrew/bin/git`（ARM）或 `/usr/local/bin/git`（Intel），而非 `/usr/bin/git`。

### 2. Permission Denied 不要用 sudo

```bash
# ❌ 错误做法
sudo brew install git        # 会破坏 ownership，导致后续操作全部报错

# ✅ 正确做法
chown -R $(whoami) $(brew --prefix)/*   # 修复权限后重试
```

brew 设计的初衷就是用户级别使用，使用 `sudo` 会改变 `/opt/homebrew` 下文件的 owner，引发连锁问题。如果误用了 `sudo brew`，用上面的命令修复即可。

### 3. 大版本升级后的迁移

```bash
# Homebrew v4 (2023+) 要求先运行迁移命令
brew update
brew doctor                     # 检查是否需要迁移
brew bump-formula-pr --arch ... # 通常无需手动干预
```

### 4. 离线环境 / 国内网络优化

中国大陆用户安装和下载可能较慢，可以通过设置镜像源加速：

```bash
# Git 仓库镜像（可选，通常无需设置，brew 官方源在国内访问正常）
# 替换为清华大学镜像
git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

# pip / npm 等有专门的镜像配置方式，这里不展开
```

### 5. Bottle vs Build from Source

brew 默认优先下载预编译的 **bottle**（二进制包），速度远快于从源码编译。某些特殊架构或定制需求时才需要从源码构建：

```bash
# 强制从源码编译（跳过 bottle）
brew install --build-from-source curl
```

### 6. 公式维护约定

brew formula 采用 "one version at a time" 策略——`brew install git` 只装最新稳定版，不保留历史版本。如果需要多版本共存（类似 nvm for Node），推荐：

- Go → 用 `gvm` 或通过 golang.org/dl 官网安装
- Python → `pyenv` 配合 `brew install pyenv`
- Node.js → `nvm`（已在本环境的 Node 章节覆盖）

## 延伸阅读

- [Homebrew 官方文档](https://docs.brew.sh)
- [[projects/mac-dev-env-setup]] — macOS 开发环境总指南
- [[technical/go]] — Go 语言环境配置
- [[technical/nodejs]] — Node.js 与 pnpm 配置