222 lines
6.7 KiB
Markdown
222 lines
6.7 KiB
Markdown
---
|
||
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 配置
|