Homebrew 使用指北：从首次安装到日常命令速查

面向 macOS 用户的 Homebrew 实用指南：安装与环境配置、Formula 和 Cask、命令速查、升级清理、依赖排查、后台服务，以及用 Brewfile 迁移软件环境。

2026年9月9日开发实践4分钟阅读

Homebrew 是 macOS 和 Linux 上的软件包管理器：搜索、安装、升级和卸载软件，都可以通过 brew 命令完成。它会自动安装软件运行所需的其他工具和组件，这些配套软件统称为“依赖”；安装记录也会保留下来，方便日后维护和迁移。

本文以 macOS 的终端应用和默认命令解释工具 Zsh 为例，Zsh 负责理解并执行你输入的命令。首次使用可以从安装开始阅读；已有使用经验可以直接查阅下方表格，再按目录跳转到具体场景。命令按 2026 年 9 月的官方文档与命令帮助核对。

表中的 tmux 是示例软件名，使用时替换为目标软件。标有“预览”的命令用于查看计划，安装、升级、卸载等命令会实际修改软件环境。

想做什么	命令
搜索软件	`brew search tmux`
查看版本、依赖和安装提示	`brew info tmux`
安装命令行工具	`brew install tmux`
安装图形应用	`brew install --cask visual-studio-code`
列出已安装软件	`brew list`
查看已安装版本	`brew list --versions tmux`
刷新 Homebrew 和软件信息	`brew update`
查看可升级软件及版本	`brew outdated --verbose`
升级指定软件	`brew upgrade tmux`
升级所有符合条件的软件	`brew upgrade`
重新安装	`brew reinstall tmux`
卸载软件	`brew uninstall tmux`
预览旧版本与缓存清理	`brew cleanup --dry-run`
执行旧版本与缓存清理	`brew cleanup`
预览闲置依赖卸载	`brew autoremove --dry-run`
卸载闲置依赖	`brew autoremove`
分层查看所需的配套软件	`brew deps --tree tmux`
查询哪些已安装软件依赖它	`brew uses --installed libevent`
检查已安装软件的依赖缺失	`brew missing`
查看后台服务	`brew services list`
导出软件清单到当前目录	`brew bundle dump`
按当前目录的清单安装	`brew bundle install`
检查 Homebrew 环境	`brew doctor`
查询某条命令的用法	`brew help install`

先检查已有安装：

brew --version

能显示版本号时，可以直接进入“安装第一个软件”。看到 command not found: brew（找不到 brew 命令）时，继续安装；曾经安装过的用户可以先查看后文“command not found: brew”的解决步骤。

使用 Homebrew 官网提供的安装命令。它会下载并运行官方安装脚本，也就是一组自动完成安装的命令，执行前可在官网检查来源：

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

按照提示安装 Xcode Command Line Tools（苹果提供的一组基础开发工具），再完成 Homebrew 安装。输入系统密码时，终端会隐藏输入字符，输完后按回车即可。安装过程可能需要输入管理员密码；日常安装软件使用自己的账号运行 brew install。

安装结束后，执行终端输出的 Next steps（接下来的步骤），让终端能找到 brew。官方默认路径如下：

平台	默认安装路径
Apple Silicon Mac（苹果 M 系列芯片）	`/opt/homebrew`
Intel Mac（英特尔芯片）	`/usr/local`
Linux	`/home/linuxbrew/.linuxbrew`

对于默认 Zsh 配置的 Apple Silicon Mac，在 ~/.zprofile 中加入下面这一行，并在当前终端执行一次：

eval "$(/opt/homebrew/bin/brew shellenv zsh)"

Intel Mac 对应使用：

eval "$(/usr/local/bin/brew shellenv zsh)"

~ 表示用户主目录，.zprofile 是 Zsh 启动时读取的配置文件之一。上面的命令会把 Homebrew 的位置加入终端查找命令的目录列表（PATH）；其中 shellenv 生成设置，eval 使设置在当前终端生效。已有这行配置时保持一份即可；通过 ZDOTDIR 自定义了 Zsh 配置目录的用户，应修改对应目录中的文件。具体系统要求和安装步骤以官方安装文档为准。

最后检查：

brew --version
brew --prefix
brew doctor

brew doctor 会列出值得检查的环境问题。逐条结合实际使用情况处理即可。

以 tmux 为例，它可以在一个终端窗口里管理多个命令行工作区：

brew search tmux
brew info tmux
brew install tmux
tmux -V

这四步依次完成搜索、查看说明、安装、验证运行版本。安装过程中出现其他软件名称，通常是 Homebrew 正在安装 tmux 所需的依赖。

日常使用时，可以把 Homebrew 管理的软件分成两类：Formula 主要是命令行工具、开发库等软件包；Cask 通常是带图形界面的完整应用。先记住这两类，就能覆盖大部分安装场景。

名称	含义	示例
Formula	一类软件包，主要包括在终端使用的工具，以及供其他程序使用的功能组件（开发库）	`brew install wget`
Cask	一类应用包，通常是带图形界面的完整软件，如浏览器、编辑器	`brew install --cask firefox`
Bottle	已经制作好的 Formula 安装包，下载后即可安装，省去在自己电脑上处理源代码的等待	`brew info` 中的 `bottled`
Tap	额外的软件源，可以理解为扩充可安装软件的“软件目录”	`brew tap` 查看已添加的软件源
Keg	某个软件的某个版本在电脑上存放的文件夹	`Cellar/tmux/版本号`
Keg-only	软件单独存放在自己的文件夹里，使用前可能需要按提示设置命令查找路径	某些指定大版本的软件、与系统自带组件同名的库

一个名字同时对应两类软件时，使用 --formula 或 --cask 指定要查看哪一类：

brew info --formula wget
brew info --cask firefox

这些术语及选项可在官方命令手册中查阅。

brew search git                    # 按名称搜索
brew search --desc terminal         # 搜索软件描述
brew info tmux                      # 版本、依赖、安装状态、注意事项
brew home tmux                      # 在浏览器中打开软件主页
brew install wget ripgrep fd        # 一次安装多个工具
brew install --cask firefox         # 安装图形应用

图形应用通常会安装到 /Applications，也就是“应用程序”文件夹，具体位置和后续设置以安装输出为准。安装完成后，重点阅读 Caveats（使用提示）：这里可能包含命令查找路径（PATH）的设置、后台服务的启动方式，或首次使用前要做的准备。

查询本机安装记录：

brew list                          # Formula 和 Cask
brew list --formula                # 仅 Formula
brew list --cask                   # 仅 Cask
brew list --versions               # 已安装 Formula 的版本
brew list --versions tmux          # 指定 Formula 的版本
brew list --installed-on-request   # 主动安装的 Formula
brew leaves                        # 没有被其他已安装包依赖的 Formula
brew list tmux                     # 查看 tmux 安装文件的路径

--installed-on-request 列出你主动选择安装的软件；leaves 列出其他已装软件都用不到的软件包。你主动安装的工具也可能被其他软件使用，所以两份清单可能有差别。

假设输出包含：

tmux ↑: 3.7b → stable 3.7c (bottled), HEAD
Installed (on request)
tmux ↑ 3.7b → 3.7c (9 files, 1.4MB) [Linked]

输出	如何理解
`↑`、`3.7b → 3.7c`	本机版本为 3.7b，存在可升级的 3.7c
`stable`	当前稳定版本
`bottled`	提供已经制作好的安装包，能否使用取决于操作系统和处理器类型
`HEAD`	可以安装软件开发者正在开发中的最新版本
`Installed (on request)`	该软件由用户主动安装
`[Linked]`	已在 Homebrew 的公共目录建立入口，让终端和其他程序能找到它
`9 files, 1.4MB`	对应安装内容的文件数量与占用空间
`Required` 下的 `✔` / `✘`	当前可安装版本所需的配套软件，在本机是否已经装好
`Recursive Runtime`	本机已装版本运行所需的全部配套软件，也包括这些软件各自需要的组件
`Caveats`	使用前需要关注的配置提示
`Analytics`	Homebrew 汇总的安装次数、从源代码生成程序时的失败次数等统计

brew info 是查询操作。确认安装版本、命令位置和实际执行版本，分别运行：

brew list --versions tmux
command -v tmux
tmux -V

当 Required 出现 ✘，同时 Recursive Runtime 显示完整，可能是新旧版本需要的配套软件有所变化。用 brew missing tmux 检查本机安装，再结合实际启动结果判断。

brew update
brew outdated --verbose
brew upgrade tmux
tmux -V

update 更新 Homebrew 本身，以及可安装软件的版本信息和安装规则；outdated 列出可升级软件；upgrade 执行软件升级。先看清单，再升级需要的软件，方便观察变化。

批量升级时可以选择范围：

brew upgrade                       # 全部符合升级条件的软件
brew upgrade --formula             # 仅 Formula
brew upgrade --cask                # 仅 Cask
brew upgrade --cask firefox        # 指定图形应用

Homebrew 默认会跳过部分自行更新、或版本标记为 latest 的 Cask。需要将这些应用纳入检查和升级时使用：

brew outdated --cask --greedy
brew upgrade --cask --greedy

安装和升级命令也可能自动刷新软件信息、升级相关依赖并清理旧版本。数据库、Node.js、Python 等关键软件升级前，先阅读对应版本的更新说明并备份业务数据。

brew pin tmux                      # 阻止 Homebrew 升级这个包
brew list --pinned                 # 查看固定清单
brew unpin tmux                    # 恢复升级

pin 保留当前已安装版本。其他软件可能需要它的新版本才能运行，固定版本期间应留意这些要求和安全更新。

有些软件会同时提供多个主要版本（也叫“大版本”）的软件包，先搜索可选版本：

brew search 'postgresql@'

选择搜索结果中的软件包名称后，使用 brew info 软件包名 查看说明和维护状态，再执行 brew install 软件包名。名称中的 @版本 表示软件源提供的指定版本；安装其他历史版本需要找到对应的安装规则，并确认它能在当前系统上使用。

不同项目需要不同版本的 Node.js、Python 时，可以使用专门的版本管理工具来切换；Homebrew 继续负责通用工具和配套组件。更多版本管理说明见官方 FAQ。

brew uninstall tmux
brew uninstall --cask firefox

普通卸载通常会保留部分用户配置和数据。卸载 Cask 应用时，--zap 会按照该应用的清理规则额外删除相关文件，可能影响个人设置或多个应用共用的文件；确认清单与备份后再使用这个选项。

先看计划：

brew cleanup --dry-run

确认后执行：

brew cleanup

也可以只处理某个软件：

brew cleanup tmux

cleanup 会处理旧版本、过时的下载文件，以及安装操作遗留的标记文件。清理旧版本后，旧安装文件夹也会被移除；需要保留旧版本时，先备份相关文件。

brew autoremove --dry-run

检查列出的软件，确认用途后执行：

brew autoremove

autoremove 会卸载那些当初为其他软件配套安装、现在已经闲置的 Formula 软件包。cleanup 主要回收旧文件，autoremove 会卸载符合条件的软件包。

缓存是 Homebrew 保存在电脑上的下载文件，方便后续重复使用。查看它们存放在哪里、占用多少空间：

brew --cache
du -sh "$(brew --cache)"

brew deps --tree tmux
brew uses --installed libevent
brew uses --installed --recursive libevent
brew missing tmux

deps 查看“运行它需要哪些配套软件”；uses 查看“哪些软件需要它”。加上 --recursive，还会继续查找依赖链上的其他软件：例如 A 需要 B、B 需要 C，查询谁需要 C 时也会包含 A。卸载某个组件之前，先看看哪些软件会用到它。

brew --prefix                      # Homebrew 的安装目录
brew --prefix tmux                 # 指向 tmux 当前版本的固定路径
brew --cellar tmux                 # tmux 各版本所在目录
command -v tmux                    # 当前终端实际使用的 tmux 命令
type -a tmux                       # 查看终端能找到的所有同名命令

在 Apple Silicon Mac 上，常见路径关系是：

路径	用途
`/opt/homebrew/Cellar/tmux/版本号/`	实际安装文件
`/opt/homebrew/opt/tmux`	名称固定，指向当前使用的版本文件夹
`/opt/homebrew/bin/tmux`	终端查找 tmux 时使用的入口

brew --prefix 软件名 可以告诉你软件预计安装在哪里；确认是否已经安装，使用 brew list --versions 软件名。

链接可以理解为指向安装文件的“快捷入口”。Homebrew 把这些入口放在公共目录里，方便终端和其他程序找到对应文件。

brew unlink tmux                   # 移除公共入口链接，保留安装文件
brew link tmux                     # 重新建立链接

创建入口时，如果同一位置已经有同名文件，Homebrew 可能提示冲突。先用下面的命令查看哪些文件会被替换：

brew link --overwrite --dry-run tmux

实际使用 --overwrite 会删除占用目标位置的文件，应先确认文件来源。标记为 keg-only 的软件包，优先按 brew info 的 Caveats 提示设置：命令行工具通常需要把所在文件夹加入 PATH，开发库可能需要告诉编译工具去哪里寻找文件。编译工具负责把程序源代码转换成电脑能运行的程序。

部分软件支持在后台持续运行，例如数据库和缓存服务。Homebrew 可以帮助启动、停止这些软件，并设置登录后自动运行。以 Redis 为例，安装后按需要选择操作：

brew install redis

操作	命令	效果
查看状态	`brew services list`	列出当前用户的服务状态
临时启动	`brew services run redis`	启动服务，保留原有的登录自动启动设置
启动并设置自启	`brew services start redis`	立即启动，并设置为登录电脑后自动启动
重启	`brew services restart redis`	重新启动，并设置为登录电脑后自动启动
停止并关闭自启	`brew services stop redis`	立即停止，并关闭登录后的自动启动
查看详情	`brew services info redis`	查看服务详细信息
清理过期服务记录	`brew services cleanup`	清理闲置服务记录

在 macOS 上，用自己的账号执行这些命令时，自动启动通常发生在登录账号之后；加上 sudo 会以管理员身份管理服务，可设置为电脑开机时启动。个人开发通常直接使用表中的命令即可。

启动后再实际连接一次，确认软件能正常响应。例如执行 redis-cli ping 向 Redis 发出测试请求，正常时会收到 PONG。软件升级后，正在后台运行的旧程序可能需要重启，才会开始使用新版本。具体用法可查询 brew help services。

Brewfile 是一份可编辑的软件清单，适合给新电脑装软件、统一团队开发环境和备份个人软件列表。它记录要装哪些软件，实际版本取决于安装时软件源提供的版本；需要恢复到完全相同的版本时，还应另外保存版本信息和对应安装包。

先建立专用目录并进入：

mkdir -p ~/Documents/brew-backup
cd ~/Documents/brew-backup
pwd
brew bundle dump --file=Brewfile

cd 切换当前目录，pwd 显示当前位置。生成的清单位于 ~/Documents/brew-backup/Brewfile，可以用编辑器打开并精简。下面是一份手写示例：

brew "git"
brew "tmux"
brew "ripgrep"
brew "fd"
cask "visual-studio-code"
cask "firefox"

再次导出并覆盖已有清单时使用 brew bundle dump --file=Brewfile --force。覆盖前先保留手工调整的内容。

先安装 Homebrew，再将 Brewfile 复制到目标电脑的目录，进入该目录执行：

brew bundle check --file=Brewfile
brew bundle install --file=Brewfile

check 检查清单里的软件是否已经装好；install 默认安装缺少的软件并升级清单中的过时软件。需要保留已有版本时，可使用：

brew bundle install --file=Brewfile --no-upgrade

安装新软件时，它需要的配套组件仍可能随之升级。个人设置、数据库里的数据、用于远程登录的 SSH 密钥文件等内容需要另行备份；换电脑时，把 Brewfile 与这些数据分别保存。官方 Brewfile 使用指南介绍了清单的更多写法。

brew bundle cleanup 会卸载清单之外的软件，也可能涉及你为其他项目安装的工具。用一份完整的 Brewfile 管理整台电脑的软件时，再使用这项操作；只列了某个项目所需工具的小清单，通常用于安装这些工具。

运行前查看 brew bundle cleanup --help，并仔细阅读终端中的确认提示。--force 会直接执行清理，使用前先确认将被移除的软件。

Homebrew 官方软件源里的软件可以直接搜索安装。某个项目要求添加额外软件源时，先核实发布者和项目安装文档，再按其说明操作：

brew tap                           # 查看已添加的额外软件源

第三方安装命令一般采用以下形式。这里的“仓库”是存放软件安装规则的在线项目，作者/仓库 和 软件名 需要替换为项目提供的真实名称：

brew tap 作者/仓库
brew install 作者/仓库/软件名
brew untap 作者/仓库

untap 移除这个软件源。通过它安装的软件，后续升级时仍需要可用的软件源提供更新。

brew analytics state               # 查看匿名统计开关
brew analytics off                 # 关闭匿名统计
brew analytics on                  # 开启匿名统计
brew config                        # 查看系统、路径和 Homebrew 环境
brew help                          # 基本帮助
brew help upgrade                  # 某条命令的完整帮助
man brew                           # 本地手册，按 q 退出

先根据处理器类型检查默认安装位置。例如 Apple Silicon Mac：

/opt/homebrew/bin/brew --version

使用这条完整路径能够显示版本时，说明 Homebrew 已经安装。接着在当前终端运行 eval "$(/opt/homebrew/bin/brew shellenv zsh)"，并按安装章节保存设置，让下次打开终端时也能找到它。如果提示这个位置找不到文件，检查实际安装位置或重新进入官方安装流程。

brew list --versions tmux
type -a tmux
command -v tmux
tmux -V

先确认 Homebrew 装的是哪个版本，再看终端实际找到了哪个文件。同名软件可能来自系统自带工具、手动安装，或 Node.js、Python 的版本管理工具。终端通常按 PATH 中的文件夹顺序查找命令；把需要的路径放在前面后，重新打开终端。一直在后台运行的软件还要单独确认正在使用的版本。

报错中的“动态库”是程序运行时需要加载的功能组件；找不到它时，程序可能启动失败。

brew missing tmux
brew info tmux
brew doctor

结合输出确认缺失依赖或旧版本问题，再执行有针对性的安装、升级或 brew reinstall tmux。重装会实际替换安装内容，通常按照软件源当前提供的版本和安装规则执行。

文件校验用来确认下载内容与官方提供的文件一致。校验失败时，下载的文件可能损坏，或与预期版本有差别。

先确认网络连接和代理设置，再对具体软件获取详细输出：

brew fetch --verbose tmux

fetch 会把软件包下载到本地缓存文件夹，可用于观察失败的下载地址。持续出现校验错误时，检查下载来源，并参考官方故障排查指南处理。使用镜像站加速下载时，应按镜像站当前文档设置软件源、软件信息查询接口（API）和安装包（Bottle）的下载地址。

运行 brew doctor，查看哪个文件夹出错、它属于哪个账号，以及建议如何修复。日常 brew install 使用安装 Homebrew 的账号；文件权限决定哪些账号可以读取或修改文件，大范围更改 /usr/local 或 /opt/homebrew 的权限会影响其他软件，应先查清具体文件夹的归属。

uname -m
type -a brew
brew --prefix
brew config

/opt/homebrew 和 /usr/local 可能分别装有面向苹果 M 系列芯片（ARM）和英特尔芯片（Intel）的 Homebrew。Rosetta 是让 M 系列 Mac 运行 Intel 软件的兼容工具，通过它运行终端时，看到的处理器类型可能有所变化。先确认项目需要哪一套，再检查终端使用的 brew 和目标软件是否来自对应的安装目录。

平时安装软件采用 search → info → install → 验证运行。定期维护分为三个阶段，上一阶段看清结果后再继续：

查更新：执行 brew update 和 brew outdated --verbose，选择本次升级的软件。
升级并验证：执行 brew upgrade 软件名，检查版本与常用功能，后台服务按需要重启。
回收空间：先执行 brew cleanup --dry-run 和 brew autoremove --dry-run，确认清理清单后再执行对应操作。

把常用软件整理进 Brewfile，日常查参数时使用 brew help 子命令。更深入的操作可以继续查阅命令手册和官方技巧集。