Homebrew 命令速查表 - macOS 包管理常用命令大全
换台新 Mac，$PATH 与依赖装得乱，半天就没了，而 Homebrew 能把这些收敛成可复现的命令。本表覆盖公式的安装/更新/卸载、Cask GUI 应用、brew services 管理后台服务、国内源切换，以及依赖查看与问题排查。不是简单罗列包名，而是告诉你该用哪个 flag 装 HEAD 分支还是预编译 bottle、以及 brew doctor 报错该怎么定位。读完基本能靠终端完成一套 Mac 工具链的搭建与修复。
典型使用场景
面向把整台开发机交给 Homebrew 管理的 macOS/Linux 工程师。日常摩擦几乎都来自四件事：brew update 只更新 Homebrew 自身索引、不升级任何包（很多人以为它会顺带升级，结果代码半年没动）；formula 与 cask 是两套体系，brew upgrade 与 brew upgrade --cask 各管一半，混用会以为「升级没生效」；bottle 下载慢或失败时需要手动切镜像；以及升级后依赖冲突、磁盘被旧版本缓存撑满时的清理路径。本表把这四条主线和 Brewfile 可复现安装一起覆盖。
基础操作 12
brew install wgetbrew uninstall wgetbrew updatebrew upgradebrew upgrade wgetbrew listbrew info wgetbrew search nginxbrew cleanupbrew outdatedbrew reinstall wgetbrew autoremoveCask GUI 应用 5
brew install --cask visual-studio-codebrew uninstall --cask visual-studio-codebrew list --caskbrew search --cask chromebrew upgrade --cask服务管理 5
brew services listbrew services start mysqlbrew services stop mysqlbrew services restart mysqlbrew services run mysql源与 Tap 5
brew tap homebrew/cask-fontsbrew untap homebrew/cask-fontsbrew tapexport HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"问题排查 7
brew doctorbrew configbrew deps wgetbrew pin wgetbrew unpin wgetbrew leavesbrew uses --installed wgetBundle 批量管理 Bundle 4
brew bundle dumpbrew bundle installbrew bundle cleanupbrew bundle check参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
brew update | 只刷新 Homebrew 自身与包索引，不会升级任何已安装包 | brew update |
brew upgrade | 升级已安装的 formula（命令行工具），GUI 应用需用 --cask | brew upgrade --cask |
brew cleanup | 删除旧版本与下载缓存，磁盘告急时见效最快的一条命令 | brew cleanup |
brew pin | 锁定版本使其不被 upgrade 动，用于「升上去就崩」的包 | brew pin wget |
brew bundle | 基于 Brewfile 导出/安装/校验，让新机器上的工具链可复现 | brew bundle dump |
易错点与避坑指南
现象跑了 brew update 之后 git、node 版本完全没变，以为命令没生效。
原因update 只刷新 Homebrew 自身与索引，升级动作在 upgrade 里。
处置先 brew outdated 看有哪些可升，再执行 brew upgrade；GUI 应用另跑 brew upgrade --cask。
现象brew install 提示某个依赖版本冲突，非要 --force-overwrite 才能装上。
原因旧版本残留与新依赖要求互斥，说明升级链路没走完。
处置先 brew update && brew upgrade，再 brew cleanup 清掉旧版本缓存，冲突仍存在才考虑 brew reinstall 该包。
现象bottle 下载极慢或反复失败，而源码编译又缺依赖装不上。
原因默认走 GitHub 的分发域名，国内网络下经常不可达。
处置临时 export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles" 后重试。
现象装完一堆工具后磁盘只剩几个 G，Caskroom/Library 里堆着多个旧版本。
原因每次升级都会保留旧版本与旧下载缓存，不会自动清理。
处置定期 brew cleanup，再 brew autoremove 移除不再需要的依赖。
现象一台机器上同时存在两套 Homebrew（arm64 与 x86_64），命令互相覆盖且 brew doctor 报警。
原因在 Apple Silicon 上装了 /usr/local 与 /opt/homebrew 两份，或从 Intel 迁移过来没清干净。
处置先 brew config 确认当前架构与 prefix，只保留一份并把它放到 PATH 最前。
排障路径
1环境出问题时先跑官方体检
brew doctor它会直接指出重复安装、PATH 顺序、缺失的 Command Line Tools 等具体问题。
2升级前先看清影响面
brew outdated && brew info wgetoutdated 给出可升级清单，info 给出版本、依赖与 caveats，破坏性变更写在 caveats 里。
3确认某包是否安装、谁在依赖它
brew list && brew deps wget && brew uses --installed wgetdeps 看它依赖谁，uses --installed 看已装的谁依赖它，二者方向相反别搞混。
4把当前工具链固化成 Brewfile 并在新机器复现
brew bundle dump && brew bundle installdump 生成 Brewfile，install 在新机器按它重建；brew bundle check 可校验是否已满足。
命令示例
安装前先查名字与依赖
brew search nginx
brew info wget
brew listbrew info 里的 caveats 常写明额外的 PATH 或配置要求，装之前值得先读一遍。
更新、评估与升级
brew update
brew outdated
brew upgrade
brew upgrade wgetupdate 只刷新 Homebrew 自身；outdated 给出可升级清单，确认后再 upgrade。
formula 与 cask 分开管理
brew install --cask visual-studio-code
brew list --cask
brew search --cask chrome
brew upgrade --cask
brew uninstall --cask visual-studio-codeGUI 应用走 cask 体系，brew upgrade 不会碰它们，必须加 --cask。
服务管理与依赖体检
brew services list
brew services start mysql
brew services run mysql
brew services restart mysql
brew services stop mysql
brew doctor
brew configstart 会加入开机自启，run 只在本次开机生效；服务 plist 在 ~/Library/LaunchAgents/。
常见坑与注意事项
- brew update 不升级任何包，别把它当成升级命令；升级是 brew upgrade 与 brew upgrade --cask 两条独立路径。
- 依赖冲突时不要直接 --force-overwrite，先用 brew info 看清冲突来源，强装会把环境搞到不可复现。
- brew cleanup 会真删旧版本与下载缓存，删完想回退只能重装，执行前用 brew leaves 确认哪些是顶层手动安装的。
- 同一台机器同时存在 arm64 与 x86_64 两套 Homebrew 会互相覆盖，命令行为诡异时先用 brew doctor 查这件事。
- bottle 下载慢或失败时先切 HOMEBREW_API_DOMAIN 与 HOMEBREW_BOTTLE_DOMAIN 镜像，别直接退回到源码编译。
提示
- 国内网络建议先换源再 install，否则 bottle 下载经常超时。
- brew services 管理的服务 plist 在 ~/Library/LaunchAgents/，出问题先看那里。
- brew cleanup 会删除旧版本和下载缓存，磁盘紧张时跑一下。
常见问题
brew update 跑完了，为什么 git 和 node 版本还是老的？
因为 update 只刷新 Homebrew 自身的代码与包索引，不会碰任何已安装包。要真正升级得跑 brew upgrade，或者只升一个包用 brew upgrade wget。升级前先用 brew outdated 看一遍可升级清单评估破坏性变更。另一个常见情况是升级只覆盖了 formula：GUI 应用属于 cask 体系，必须用 brew upgrade --cask 才会动，brew list 与 brew list --cask 也是分开的两份清单。
安装命令到底怎么写才不用猜名字？
三步。brew search nginx 模糊搜出准确包名；brew info wget 看版本、依赖和 caveats，装之前确认依赖是否符合预期；brew list 核对是否已经装过、装的是哪个版本。Cask 侧对应命令是 brew search --cask chrome 与 brew list --cask。装错名字时不要直接 --force-overwrite，先 brew info 看依赖冲突的真实原因。
磁盘被旧版本和缓存撑满，先跑哪条命令？
brew cleanup，它删除旧版本与下载缓存，是见效最快的一条。接着可以 brew autoremove 清掉不再被需要的依赖，以及 brew bundle cleanup 清掉 Brewfile 里未列出的包。执行前先用 brew leaves 看哪些是顶层手动安装的，确认没有误删你确实在用的东西。Cask 的旧版本残留在 Caskroom 目录里，同样由 cleanup 处理。
某工具一升级就崩，怎么固定住版本？
用 brew pin wget 把它锁住，brew upgrade 会跳过被 pin 的包；等上游修好了用 brew unpin wget 解除。想查清是哪个已安装的包依赖它，跑 brew uses --installed wget；看它自身依赖用 brew deps wget。确认整体环境是否正常则交给 brew doctor 与 brew config。
怎么让一台新机器上的工具链和现在完全一致？
四条命令形成一个闭环：brew bundle dump 把当前已安装列表导出成 Brewfile；把 Brewfile 提交进仓库；新机器上 brew bundle install 按它批量安装；brew bundle check 校验是否已满足依赖，brew bundle cleanup 清掉 Brewfile 之外多装的包。配 cask 的话同样写进 Brewfile，一并由 bundle 管理。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。