6.7 KiB
tags, create time
| tags | 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/ |
# Formula 安装
brew install git
# Cask 安装（注意 --cask 或直接用 install，brew v4+ 自动识别）
brew install --cask visual-studio-code
Tap —— 第三方仓库
默认只包含 Homebrew 官方的 core tap（formula + cask）。社区维护的第三方仓库称为 tap。
# 查看已添加的 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
代码示例
安装与初始化
# 一键安装脚本
/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 将其应用到当前环境。
常用工作流
# 搜索包（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 # 查看当前配置信息
管理依赖
# 查看某包的依赖树
brew deps --tree git
# 查看哪些包依赖某包（反向查询）
brew depends --tag python@3.12
# 列出已安装的包
brew list
# 列出可卸载的孤立依赖（无人引用）
brew autoremove
[!warning] autoremove 不会删除你显式安装的包 只有那些因满足其他包的依赖而被自动安装、且当前不再被任何包需要的依赖才会被移除。
源码编译自定义参数
# 查看可用选项
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 之前：
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
# ❌ 错误做法
sudo brew install git # 会破坏 ownership，导致后续操作全部报错
# ✅ 正确做法
chown -R $(whoami) $(brew --prefix)/* # 修复权限后重试
brew 设计的初衷就是用户级别使用，使用 sudo 会改变 /opt/homebrew 下文件的 owner，引发连锁问题。如果误用了 sudo brew，用上面的命令修复即可。
3. 大版本升级后的迁移
# Homebrew v4 (2023+) 要求先运行迁移命令
brew update
brew doctor # 检查是否需要迁移
brew bump-formula-pr --arch ... # 通常无需手动干预
4. 离线环境 / 国内网络优化
中国大陆用户安装和下载可能较慢，可以通过设置镜像源加速：
# 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（二进制包），速度远快于从源码编译。某些特殊架构或定制需求时才需要从源码构建：
# 强制从源码编译（跳过 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 官方文档
- projects/mac-dev-env-setup — macOS 开发环境总指南
- technical/go — Go 语言环境配置
- technical/nodejs — Node.js 与 pnpm 配置