Homebrew 安装与使用完全指南：macOS 与 Linux 的 brew 命令实战

更新日期：2026-09-27

Homebrew 是 macOS 和 Linux 上最流行的包管理器，macOS 用户习惯叫它"缺的东西 brew 都有"，Linux 社区则称其为 Linuxbrew。它能一行命令安装命令行工具、图形应用、字体乃至特定版本的开发运行时，并把它们统一管理、统一升级、统一卸载——这是手动下载 pkg 或拖 dmg 无法比拟的。

本篇覆盖安装（含 Apple Silicon 与 Intel 的路径差异、Linux 发行版要求）、日常最常用的 brew 命令、Cask 图形应用管理、Brewfile 批量恢复环境、国内镜像加速，以及卸载与故障排查。命令在 macOS 与 Linux 通用，差异处单独标注。

一、安装前的准备

macOS：需要 macOS 12（Monterey）或更高版本；安装 Xcode Command Line Tools 即可，不需要完整的 Xcode（安装过程中系统会自动弹窗引导）。检查是否已装：xcode-select --install，已装会提示已存在。

Linux：官方支持主流 64 位发行版（Ubuntu/Debian、RHEL 系等），依赖编译工具链与 curl、git、file 等基础工具，Debian/Ubuntu 上一条命令补齐：

sudo apt-get install build-essential procps curl file git

磁盘与网络：预留至少 5GB 空间；安装脚本从 GitHub 拉取，国内网络环境建议先看第六节的镜像加速，避免下载中断。

二、安装 Homebrew

官方安装脚本一条命令完成（macOS 与 Linux 相同）：

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

脚本执行时会说明它要做什么、装到哪里，按回车确认后开始下载。几个关键路径因平台和芯片而异：

安装后的关键一步：配置 PATH。 Apple Silicon 与 Linux 上，安装结束脚本会提示两行命令，务必执行（以 Apple Silicon 为例）：

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

漏掉这一步是最常见的"装完了却 command not found: brew"的原因。执行后验证：

brew --version
brew doctor

brew doctor 是 Homebrew 的自检命令，会列出配置问题与修复建议，装完先跑一次是好习惯。

安装脚本到底做了什么：它先检查并安装依赖（macOS 装 Command Line Tools，Linux 装编译链），然后在默认前缀下创建目录结构，git clone 拉取 brew 主仓库与核心包索引（homebrew-core），最后生成提示你配置 PATH。理解这一点有助于排障：所有与"下载慢""索引旧"相关的问题，本质都是那几个 git 仓库的网络问题，换镜像（第六节）解决的正是它们。

三、多版本运行时：版本化包名的用法

开发工具链最常见的需求是"同时要两个版本"。Homebrew 的答案是版本化包名（formula 里的 @ 后缀）：

brew install node@20    # 安装 20.x 系列
brew install node@22    # 与 20.x 并存
brew link --overwrite node@22   # 切换默认指向的版本

要点与边界：版本化包之间可以共存，同一时间只有一个被 link 到 PATH；brew upgrade 不会跨大版本升级（node@20 不会自动变 22），这让生产环境的版本锁定更可控；但 Homebrew 不支持安装任意历史小版本，需要精确版本锁定时，nvm/pyenv 这类专用版本管理器仍不可替代。分工建议：系统级工具交给 brew，语言运行时版本管理交给专用工具——两者装同一个包是混乱之源。

四、日常最高频的命令

# 搜索软件包
brew search wget

# 安装（命令行工具）
brew install wget

# 安装特定版本（从版本历史安装）
brew install node@20

# 查看已安装列表
brew list
brew list --versions wget

# 查看某个包的信息（依赖、主页、安装路径）
brew info wget

# 升级自身并升级所有已安装的包
brew update && brew upgrade

# 只升级某个包
brew upgrade wget

# 卸载
brew uninstall wget

# 清理旧版本缓存，释放磁盘
brew cleanup

brew update 更新的是 brew 自身与软件包索引（相当于 apt 的 update），brew upgrade 才是真正升级软件包，两者通常连着用。磁盘紧张的机器定期跑 brew cleanup 能回收几个 GB 的旧版本缓存。

五、Cask：用 brew 装图形应用

macOS 上 Homebrew 还能安装图形应用（Chrome、VS Code、iTerm2 等），这类包叫 Cask：

# 安装图形应用
brew install --cask visual-studio-code
brew install --cask google-chrome

# 查看可用的 cask
brew search --cask chrome

# 升级与卸载
brew upgrade --cask
brew uninstall --cask google-chrome

Cask 安装的应用出现在系统的"应用程序"目录，与手动安装的无差别，但升级只需一条 brew upgrade --cask。新装机场景下，命令行工具 + Cask 组合能把整台机器的环境安装压缩成十几行脚本。

六、Brewfile：一键恢复整台机器的环境

Homebrew 支持把当前安装的所有包导出为一个 Brewfile，在新机器上批量还原：

# 在旧机器上导出（需要先安装 bundle 扩展，新版本已内置）
brew bundle dump --file=~/Brewfile

# Brewfile 内容形如：
#   brew "wget"
#   brew "node@20"
#   cask "visual-studio-code"

# 在新机器上批量安装
brew bundle --file=~/Brewfile

把 Brewfile 提交进个人的 dotfiles 仓库，重装系统或换新电脑时一条命令恢复全部工具链——这是 Homebrew 对开发者最有价值却最少人用的功能。

七、国内网络环境：镜像加速

安装与更新慢或失败的根源是访问 GitHub 与 Homebrew 官方源不稳定。通用解法是把 Homebrew 的几个仓库换成国内镜像（如清华大学 TUNA、中科大 USTC 镜像，配置方法见各镜像站的 Homebrew 页面，按提示替换 origin 即可）：

# 查看当前使用的仓库地址
cd "$(brew --repository)" && git remote -v
cd "$(brew --repository homebrew/core)" 2>/dev/null && git remote -v

替换镜像后 brew update 的速度会恢复正常水平。注意：镜像站同步存在小时级延迟，个别刚发布的包版本可能要等同步；遇到"找不到版本"时先排除这个因素再排查其他原因。 bottles（预编译二进制包）的下载地址同样可配置镜像，镜像站文档中有对应的环境变量写法。

八、服务管理：brew services

macOS 上 Homebrew 还能托管后台服务（nginx、redis、postgresql 等），替代手写 launchd 配置：

brew services start nginx     # 启动并开机自启
brew services stop nginx
brew services restart nginx
brew services list            # 查看所有托管服务的状态

Linux 上对应 systemd，brew services 会适配。开发本机的"随手起一个 redis"场景，这比写 systemd 单元或 docker-compose 更轻。

九、卸载与故障排查

完全卸载 Homebrew（官方卸载脚本，与安装脚本对称）：

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

常见问题速查：

1. command not found: brew——PATH 未配置或未生效，回到第二节检查 shellenv 两行，并确认写对了 shell 配置文件（zsh 是 ~/.zprofile，bash 是 ~/.bash_profile）。
2. brew install 报权限错误——不要用 sudo 跑 brew，Homebrew 设计上禁止 root 运行；检查前缀目录的属主：sudo chown -R $(whoami) $(brew --prefix)/*。
3. 升级后命令行为异常——先 brew doctor，多数是链接未刷新，brew link --overwrite <包名> 可解。
4. 某个包升级后不兼容——用 brew search 确认可用版本，回退到版本化包名（如 node@20）；Homebrew 不直接支持安装任意历史版本，这是它与 apt/nvm 等工具的显著差异。
5. Linux 上 brew 装的命令与系统包冲突——优先级由 PATH 顺序决定，把 linuxbrew 路径放在系统路径之后可让系统包优先。

十、Tap：第三方软件仓库

Homebrew 的包不止官方仓库——任何人或组织都可以维护自己的仓库（Tap），安装官方没有的软件：

# 添加第三方 tap（常见的如 chromedriver 等版本化二进制）
brew tap user/repo
brew install user/repo/toolname

# 查看已添加的 tap，移除不再需要的
brew tap
brew untap user/repo

使用第三方 tap 时把它当作"安装第三方二进制"来审视：维护者是谁、脚本做什么、更新是否活跃——tap 里的 formula 本质是可以执行任意代码的安装脚本，与直接跑陌生脚本同等对待。知名软件的官方 tap（如各语言版本管理器提供的）通常可信度较高。

十一、常见问题扩展排查

brew update 长时间卡在 Updating Homebrew：本质是 git 对 GitHub 的拉取超时。先 git remote -v 确认仓库地址，网络受限环境换镜像（第六节）；也可以设置环境变量让 update 静默跳过过长的检查（HOMEBREW_NO_AUTO_UPDATE=1），改为手动控制更新时机。

镜像站 404 或找不到包版本：镜像同步延迟所致，等同步或临时切回官方源验证；不要在镜像不同步时反复 update，那只会污染本地索引状态。

Apple Silicon 上装了 x86 包：Intel 版 Homebrew（在 /usr/local）与 ARM 版（在 /opt/homebrew）可以并存，误装 x86 版的典型症状是所有包都要走 Rosetta 转译、性能打折。检查 which brew 的路径，把 PATH 中 x86 路径清理掉，用 ARM 前缀的 brew 重装所需包。

磁盘占用持续增长：缓存与旧版本是主因。brew cleanup --prune=all 深度清理；du -sh $(brew --cache) 看缓存总量；Cask 应用的旧版本同样会被 cleanup 处理。

十二、macOS 与 Linux 的差异速查

Linux 上 Homebrew 的定位是"用户态的现代工具链"（新版本 git、fzf、jq 等），系统级软件仍归发行版包管理器管——它不需要也不应该替代 apt。

十六、脚本与自动化：让 brew 进入你的工具链

Homebrew 的命令输出对机器同样友好，几个值得纳入自动化工具链的用法：

# 列出手动安装的顶层包（过滤依赖项，适合生成 Brewfile 草稿）
brew leaves

# 查询有更新可用的包（巡检脚本用）
brew outdated

# JSON 输出供脚本处理（版本、依赖、官网一应俱全）
brew info --json=v2 wget | jq '.formula[0].installed[0].version'

brew outdated 配合 cron 或启动脚本，就是一台"软件包有更新"巡检器；brew list --json 则是写装机脚本的可靠数据源——用机器可读的输出替代肉眼解析终端表格，脚本才不会因格式微调而坏掉。CI 环境里如果依赖 brew 安装工具，固定版本化包名并配合缓存，能把安装时间从几分钟压到十几秒。

镜像加速还有一个高频场景值得单独说：bottles（预编译包）的下载地址与 formula 索引是分开配置的。换了 formula 镜像但 bottle 仍走官方时，会出现"索引快、下载慢"的组合症状——镜像站帮助文档里的 HOMEBREW_BOTTLE_DOMAIN 环境变量就是为这个准备的，两者一起换才能全程加速。

维护角度还有一个常被忽视的命令组合：brew deps <包> 与 brew uses --installed <包>，前者回答"这个包依赖什么"，后者回答"我装的哪些包依赖它"。卸载前的依赖检查、评估"升级某基础库影响面"时，这两个命令比搜索引擎快得多。Homebrew 的包索引本身就是一张活的依赖图，把它当数据库用，是这款工具进阶玩法里性价比最高的一个。

十六、高频问答

brew 和 App Store 装的应用冲突吗？ 不冲突但可能重复：同一应用两个渠道各装一份会各自更新，建议二选一，Cask 装的应用在 App Store 里也会显示可更新属正常现象，选一个来源管理。

公司电脑没管理员权限能装吗？ 可以走"非默认前缀"安装（安装脚本支持自定义安装目录），无需 sudo，但部分依赖系统目录的 cask 会受限，具体看软件本身的权限需求。

brew upgrade 要不要定期跑？ 日常工具建议每周一次；生产依赖相关的工具链升级前先看 changelog，配合版本化包名（node@20 这类）控制升级节奏，避免"顺手全量升级"带来意外。

装错了版本想回退怎么办？ 优先装另一个版本化包并存，brew link 切换；Homebrew 不提供任意历史版本的回滚，这是它和 nvm/pyenv 的核心差异，也是关键工具链建议交给专用版本管理器的原因。

十三、命令速查表

brew search <名字>            # 搜索
brew install <包>             # 安装
brew install --cask <应用>    # 安装图形应用（macOS）
brew list                     # 已安装列表
brew info <包>                # 包信息与依赖
brew update && brew upgrade   # 更新索引并升级全部
brew uninstall <包>           # 卸载
brew cleanup                  # 清理旧版本缓存
brew doctor                   # 自检
brew services start <服务>    # 托管后台服务
brew bundle dump              # 导出 Brewfile
brew bundle install           # 按 Brewfile 批量安装

十四、真实场景：一台新 Mac 的前端开发环境

把上面的能力串成新机装机的完整序列，这也是 Brewfile 价值的直观展示：

# 1. 安装 Homebrew（第二节脚本）
# 2. 配置 PATH 并生效
eval "$(/opt/homebrew/bin/brew shellenv)"

# 3. 基础工具链
brew install git wget fzf jq node@22 pnpm

# 4. 图形应用
brew install --cask visual-studio-code google-chrome iterm2 docker

# 5. 常驻服务（本地开发的数据库）
brew services start postgresql@16

八条命令之后，一台新 Mac 就具备完整的 Web 开发环境。把这个序列维护成 Brewfile 或安装脚本存进 dotfiles 仓库，下次重装系统只需执行一遍——机器是消耗品，环境定义才是资产。

几个顺手的技巧：brew search --desc 关键词 连描述一起搜索，比纯名字匹配更容易定位包；安装前留意输出末尾的 caveats 段——Homebrew 会把每个包装后需要的手工步骤（PATH 提示、服务注册等）写在里面，这是官方文档之外最实用的安装后指引；brew doctor 的输出把问题分成 warning 与 error，error 必须处理（仓库冲突、权限损坏），warning 多为建议性提示，遇到不理解的条目直接搜原文，常见条目都有成熟答案。

十五、和系统包管理器怎么分工

macOS 没有原生包管理器，Homebrew 是事实标准，没有取舍问题。Linux 上 Homebrew 与 apt/yum 并存时的分工建议：系统级服务（内核模块、驱动、系统库）交给发行版包管理器；开发工具链、多版本运行时（node、python、go 的特定版本）交给 Homebrew 或专用版本管理器（nvm、pyenv）。同一台机器混用没问题，但避免用两个管理器装同一个包，否则升级来源混乱、排障成本高。

官方资料与继续阅读

• Homebrew 官网与安装文档：https://brew.sh
• Homebrew 官方 GitHub 仓库（安装脚本源码）：https://github.com/Homebrew/brew
• 清华大学 TUNA 镜像站 Homebrew 帮助页：https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/
• 站内相关文章：Claude Code 安装指南、Ubuntu 安装 Docker 完整教程、Linux sysctl.d 持久化配置教程