Homebrew 安装指南

一、概述

1.1 什么是 Homebrew

Homebrew 是 macOS（和 Linux）上最流行的开源包管理器，被称为 "The Missing Package Manager for macOS"。它让你通过一条命令即可安装、更新、卸载命令行工具和桌面应用。

核心术语：

术语	含义
Formula	命令行软件包的安装脚本（如 git、wget、node）
Cask	GUI 桌面应用的安装脚本（如 Chrome、VS Code、Docker Desktop）
Bottle	预编译的二进制包，免去编译等待
Tap	第三方 Formula/Cask 仓库源
Cellar	Formula 的安装目录（`/opt/homebrew/Cellar`）
Caskroom	Cask 的安装目录（`/opt/homebrew/Caskroom`）
Keg	Cellar 中某个 Formula 的特定版本目录
Brewfile	声明式依赖清单文件，用于批量管理

1.2 版本信息

项目	说明
当前主线版本	Homebrew 4.x（截至 2025 年最新为 4.5+）
官网	https://brew.sh
GitHub	https://github.com/Homebrew/brew
文档	https://docs.brew.sh
Formula 搜索	https://formulae.brew.sh

1.3 安装路径

架构	安装前缀
Apple Silicon（M1/M2/M3/M4）	`/opt/homebrew`
macOS Intel	`/usr/local`
Linux	`/home/linuxbrew/.linuxbrew`

二、系统要求

2.1 macOS 要求

处理器：Apple Silicon（M1/M2/M3/M4）或 64 位 Intel CPU
系统版本：macOS Sonoma（14）或更高版本
Xcode CLT：必须安装 Command Line Tools for Xcode
Shell：需要 Bash（安装脚本使用 Bash 执行）
磁盘空间：建议预留 ≥ 5 GB

2.2 Linux 要求（可选）

Homebrew 也支持 Linux（称为 Linuxbrew），需要：

GCC 4.7.0+
Linux 4.2+（推荐 glibc 2.13+）
64 位 x86_64 或 ARM64 架构

三、安装 Homebrew

3.1 安装前准备

检查是否已安装

Bash

brew --version
# 如果返回版本号，说明已安装
which brew

安装 Xcode Command Line Tools

Bash

xcode-select --install

弹出对话框后点击「安装」，等待下载完成（约 1~2 GB）。

验证 CLT 安装

Bash

xcode-select -p
# 应输出：/Library/Developer/CommandLineTools

3.2 方式一：官方脚本安装（推荐）

Bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

脚本会：

检查系统环境
提示确认安装路径和操作
下载并安装 Homebrew 到默认前缀
完成后提示配置 PATH

Apple Silicon 用户注意

安装完成后，脚本会提示你执行两条命令来配置 PATH。必须执行，否则 brew 命令不可用。

配置 Shell 环境变量

安装完成后，根据你的 Shell 类型配置 PATH：

Bash

# 检查当前 Shell 类型
echo $SHELL

Zsh（macOS 默认）：

Bash

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Bash：

Bash

echo >> ~/.bash_profile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
eval "$(/opt/homebrew/bin/brew shellenv)"

Shell 说明

macOS Catalina（10.15）起默认 Shell 已从 Bash 切换为 Zsh。如果你没有手动更改过，使用 ~/.zprofile 即可。Intel Mac 用户将路径中的 /opt/homebrew 替换为 /usr/local。

3.3 方式二：.pkg 安装器

Homebrew 也提供 macOS .pkg 安装包：

访问 https://github.com/Homebrew/brew/releases/latest
下载 .pkg 文件
双击运行安装
安装器会自动配置 PATH（无需手动操作）

3.4 方式三：国内镜像安装（网络受限推荐）

如果直接访问 GitHub 速度过慢或无法连接，使用国内镜像：

中科大（USTC）镜像：

Bash

/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"

清华大学（TUNA）镜像：

Bash

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3.5 验证安装

Bash

# 查看版本
brew --version

# 运行诊断
brew doctor

# 查看配置
brew config

brew doctor 会检查系统环境并给出修复建议。理想输出：

Text

Your system is ready to brew.

四、国内镜像加速配置

强烈建议

在中国大陆使用 Homebrew，配置镜像是必需步骤，否则 brew update 和 brew install 会非常缓慢甚至超时。

4.1 镜像源对比

镜像源	提供方	稳定性	速度	推荐度
USTC	中国科学技术大学	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
TUNA	清华大学	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Aliyun	阿里云	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐

4.2 配置 USTC 镜像（推荐）

Bash

# 检查当前 Shell
echo $SHELL

Zsh 用户（macOS 默认）编辑 ~/.zshrc：

Bash

cat >> ~/.zshrc << 'EOF'
# Homebrew 镜像加速（USTC）
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
EOF

source ~/.zshrc

Bash 用户编辑 ~/.bash_profile：

Bash

cat >> ~/.bash_profile << 'EOF'
# Homebrew 镜像加速（USTC）
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
EOF

source ~/.bash_profile

4.3 配置 TUNA 镜像（备选）

Bash

# Zsh 用户
cat >> ~/.zshrc << 'EOF'
# Homebrew 镜像加速（TUNA）
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
EOF

source ~/.zshrc

4.4 配置 Aliyun 镜像（备选）

Bash

# Zsh 用户
cat >> ~/.zshrc << 'EOF'
# Homebrew 镜像加速（Aliyun）
export HOMEBREW_API_DOMAIN="https://mirrors.aliyun.com/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.aliyun.com/homebrew/homebrew-bottles"
EOF

source ~/.zshrc

4.5 验证镜像生效

Bash

# 查看当前环境变量
brew config | grep -E 'HOMEBREW_(API|BREW_GIT|CORE_GIT|BOTTLE)'

# 测试更新速度
time brew update

4.6 恢复官方源

Bash

# 删除环境变量（编辑对应的 Shell 配置文件，删除 Homebrew 镜像相关行）
unset HOMEBREW_API_DOMAIN
unset HOMEBREW_BREW_GIT_REMOTE
unset HOMEBREW_CORE_GIT_REMOTE
unset HOMEBREW_BOTTLE_DOMAIN

# 重置 Homebrew 远程仓库
brew update-reset

五、日常使用

5.1 搜索软件

Bash

# 搜索 Formula（命令行工具）
brew search wget

# 搜索 Cask（GUI 应用）
brew search --cask chrome

# 在线搜索（更全面）
# 访问 https://formulae.brew.sh

5.2 安装软件

Bash

# 安装 Formula
brew install git
brew install wget
brew install node

# 安装 Cask（GUI 应用）
brew install --cask visual-studio-code
brew install --cask google-chrome
brew install --cask docker
brew install --cask iterm2

# 安装指定版本
brew install python@3.12

5.3 查看已安装软件

Bash

# 列出所有已安装 Formula
brew list --formula

# 列出所有已安装 Cask
brew list --cask

# 列出所有（Formula + Cask）
brew list

# 查看某个软件的详细信息
brew info git
brew info --cask docker

# 查看顶层包（非依赖安装）
brew leaves

5.4 更新软件

Bash

# 更新 Homebrew 自身及仓库索引
brew update

# 查看可升级的软件
brew outdated

# 升级所有软件
brew upgrade

# 升级指定软件
brew upgrade git
brew upgrade --cask docker

# 锁定某个软件不被升级
brew pin node
brew unpin node

5.5 卸载软件

Bash

# 卸载
brew uninstall wget
brew uninstall --cask google-chrome

# 卸载并删除所有版本
brew uninstall --force wget

5.6 清理缓存

Bash

# 查看可清理空间
brew cleanup -n

# 执行清理（删除旧版本和缓存）
brew cleanup

# 清理所有缓存（包括最新版本的下载缓存）
brew cleanup -s

# 查看缓存目录大小
du -sh $(brew --cache)

六、Tap（第三方仓库）

6.1 概念

Tap 是第三方 Formula/Cask 仓库，让你可以安装不在官方仓库中的软件。

6.2 常用命令

Bash

# 查看已添加的 Tap
brew tap

# 添加 Tap
brew tap homebrew/services
brew tap homebrew/cask-fonts

# 从 Tap 安装
brew install font-fira-code

# 移除 Tap
brew untap homebrew/cask-fonts

6.3 常用第三方 Tap

Tap	用途
`homebrew/services`	管理后台服务（启动/停止/重启）
`homebrew/cask-fonts`	安装字体（Fira Code、JetBrains Mono 等）
`homebrew/cask-versions`	安装软件的历史版本

七、Services（服务管理）

7.1 概念

brew services 用于管理通过 Homebrew 安装的后台服务（如 MySQL、Redis、PostgreSQL、Nginx）。

7.2 常用命令

Bash

# 列出所有服务及状态
brew services list

# 启动服务（开机自启）
brew services start mysql

# 停止服务
brew services stop mysql

# 重启服务
brew services restart mysql

# 仅运行一次（不设置开机自启）
brew services run mysql

# 停止所有服务
brew services stop --all

# 清理无效的服务配置
brew services cleanup

7.3 服务管理示例

Bash

# 安装并启动 MySQL
brew install mysql
brew services start mysql

# 安装并启动 Redis
brew install redis
brew services start redis

# 安装并启动 PostgreSQL
brew install postgresql@16
brew services start postgresql@16

# 查看服务状态
brew services list
# Name       Status  User    File
# mysql      started refinex ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
# redis      started refinex ~/Library/LaunchAgents/homebrew.mxcl.redis.plist
# postgresql started refinex ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

八、Brewfile（声明式管理）

8.1 概念

Brewfile 是一个声明式依赖清单文件，类似 Ruby 的 Gemfile。它让你可以：

一键还原整台机器的软件环境
版本控制你的软件清单
在多台 Mac 之间同步环境

8.2 基本语法

Ruby

# Brewfile 示例

# Taps
tap "homebrew/services"
tap "homebrew/cask-fonts"

# 命令行工具（Formula）
brew "git"
brew "wget"
brew "node"
brew "python@3.12"
brew "jq"
brew "tree"
brew "htop"
brew "tldr"

# GUI 应用（Cask）
cask "visual-studio-code"
cask "google-chrome"
cask "docker"
cask "iterm2"
cask "postman"
cask "raycast"

# 字体
cask "font-fira-code"
cask "font-jetbrains-mono"

# Mac App Store 应用（需要 mas-cli）
# brew "mas"
# mas "WeChat", id: 836500024

8.3 常用命令

Bash

# 从当前已安装的软件生成 Brewfile
brew bundle dump

# 生成并覆盖已有 Brewfile
brew bundle dump --force

# 从 Brewfile 安装所有软件
brew bundle install

# 简写（默认读取当前目录的 Brewfile）
brew bundle

# 检查是否所有依赖已安装
brew bundle check

# 删除 Brewfile 中未列出的软件
brew bundle cleanup

# 干运行（仅显示会删除什么）
brew bundle cleanup --force --dry-run

# 指定 Brewfile 路径
brew bundle --file=~/dotfiles/Brewfile

8.4 最佳实践

将 Brewfile 纳入 dotfiles 仓库进行版本控制
新机器到手后 brew bundle --file=~/dotfiles/Brewfile 一键还原
定期执行 brew bundle dump --force 更新清单
使用 brew bundle cleanup 清理多余软件

九、开发者常用 Formula 推荐

9.1 基础工具

Bash

brew install git           # 版本控制
brew install wget          # 下载工具
brew install curl          # HTTP 客户端（macOS 自带但版本旧）
brew install jq            # JSON 处理
brew install yq            # YAML 处理
brew install tree          # 目录树展示
brew install htop          # 进程监控
brew install tldr          # 简化版 man
brew install bat           # 增强版 cat
brew install fd            # 增强版 find
brew install ripgrep       # 增强版 grep
brew install fzf           # 模糊搜索
brew install eza           # 增强版 ls（原 exa）

9.2 开发语言与运行时

Bash

brew install node          # Node.js
brew install python@3.12   # Python
brew install go            # Go
brew install rust          # Rust
brew install openjdk@21    # Java 21

9.3 数据库

Bash

brew install mysql         # MySQL
brew install postgresql@16 # PostgreSQL 16
brew install redis         # Redis
brew install sqlite        # SQLite

9.4 容器与云

Bash

brew install --cask docker  # Docker Desktop
brew install kubectl         # Kubernetes CLI
brew install helm            # Helm
brew install terraform       # Terraform

9.5 推荐 Cask 应用

Bash

brew install --cask visual-studio-code  # VS Code
brew install --cask iterm2              # 终端
brew install --cask postman             # API 测试
brew install --cask raycast             # 启动器（替代 Spotlight）
brew install --cask arc                 # Arc 浏览器
brew install --cask notion              # Notion
brew install --cask obsidian            # Obsidian
brew install --cask rectangle           # 窗口管理

十、故障排查

10.1 诊断命令

Bash

# 全面诊断
brew doctor

# 查看配置和环境
brew config

# 查看 Homebrew 安装前缀
brew --prefix

# 查看某个包的安装路径
brew --prefix git

# 查看某个包的依赖
brew deps --tree git

10.2 常见问题

问题 1：`brew` 命令找不到

原因：PATH 未正确配置。

Bash

# Apple Silicon
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
eval "$(/usr/local/bin/brew shellenv)"

然后将上述命令写入 Shell 配置文件（见第三章）。

问题 2：`brew update` 超时

原因：网络无法访问 GitHub。

解决：配置国内镜像（见第四章）。

问题 3：权限错误

Bash

# 修复 Homebrew 目录权限
sudo chown -R $(whoami) $(brew --prefix)/*

# 或更精确地修复
sudo chown -R $(whoami) /opt/homebrew/Cellar /opt/homebrew/Caskroom /opt/homebrew/Frameworks /opt/homebrew/bin /opt/homebrew/etc /opt/homebrew/include /opt/homebrew/lib /opt/homebrew/opt /opt/homebrew/sbin /opt/homebrew/share /opt/homebrew/var

问题 4：Bottle 下载失败

Bash

# 使用镜像（见第四章）或从源码编译
brew install --build-from-source <formula>

问题 5：某个 Formula 与系统冲突

Bash

# 查看链接状态
brew link --overwrite <formula>

# 或取消链接
brew unlink <formula>

问题 6：磁盘空间不足

Bash

# 清理缓存和旧版本
brew cleanup

# 查看 Homebrew 占用
du -sh /opt/homebrew
du -sh $(brew --cache)

十一、卸载 Homebrew

Bash

# 官方卸载脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

警告

卸载会删除所有通过 Homebrew 安装的软件。建议先执行 brew bundle dump 备份 Brewfile。

手动清理残留：

Bash

# Apple Silicon
sudo rm -rf /opt/homebrew

# Intel Mac
sudo rm -rf /usr/local/Homebrew
sudo rm -rf /usr/local/Caskroom
sudo rm -rf /usr/local/Cellar

# 清理缓存
rm -rf ~/Library/Caches/Homebrew
rm -rf ~/Library/Logs/Homebrew

# 删除 Shell 配置中的 Homebrew 相关环境变量

十二、速查手册

12.1 核心命令

命令	说明
`brew install <pkg>`	安装 Formula
`brew install --cask <app>`	安装 Cask（GUI 应用）
`brew uninstall <pkg>`	卸载
`brew search <keyword>`	搜索
`brew info <pkg>`	查看软件信息
`brew list`	列出已安装软件
`brew leaves`	列出顶层包
`brew update`	更新 Homebrew 及索引
`brew outdated`	查看可升级的软件
`brew upgrade`	升级所有软件
`brew upgrade <pkg>`	升级指定软件
`brew pin <pkg>`	锁定版本不升级
`brew unpin <pkg>`	解锁版本
`brew cleanup`	清理旧版本和缓存
`brew doctor`	诊断问题
`brew config`	查看配置

12.2 Tap 与 Services

命令	说明
`brew tap`	列出已添加的 Tap
`brew tap <user/repo>`	添加第三方 Tap
`brew untap <user/repo>`	移除 Tap
`brew services list`	列出所有服务
`brew services start <svc>`	启动服务（开机自启）
`brew services stop <svc>`	停止服务
`brew services restart <svc>`	重启服务
`brew services run <svc>`	运行一次（不自启）

12.3 Bundle

命令	说明
`brew bundle dump`	导出当前安装为 Brewfile
`brew bundle install`	从 Brewfile 安装
`brew bundle check`	检查是否满足依赖
`brew bundle cleanup`	清理 Brewfile 之外的软件