wonder/Qiniu

Fork 0

Files

T

wonder a5e418c701 vault backup: 2026-07-01 23:09:21

2026-07-01 23:09:21 +08:00

6.7 KiB

Raw Blame History

tags, create time

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 章节覆盖）

6.7 KiB Raw Blame History Unescape Escape