简介：Homebrew 是苹果 macOS 系统上一款广受欢迎的开源软件包管理工具，这份资源围绕其安装、配置与日常运维提供系统性讲解，旨在帮助开发者摆脱手动编译和依赖管理的繁琐，通过简洁命令完成软件包的搜索、安装、升级与卸载。内容涵盖 brew search、list、update、upgrade、uninstall 等常用命令，以及 Homebrew Cask 管理图形界面应用、自定义 tap 扩展非官方软件源、brew doctor 健康检查与 cleanup 清理旧版本等核心功能，并深入说明 Cellar、Library、bin 等目录结构与工作流程，同时提供面对更新冲突、依赖异常等常见问题的排错思路。资源按功能模块组织，既适合刚接触苹果开发环境的新手逐步上手，也可作为中高级开发者日常维护效率手册。资源共 2000 个文件，以 Ruby 脚本（rb）为主，辅以 Markdown 文档、YAML 配置、JSON 数据及示例文件，分别承担核心逻辑、使用说明、配置模板与演示功能，压缩包整体约 421.56 兆字节。目前已有超过 2.1 万人学习下载，实用性与社区认可度高；通过本资源可系统掌握 Homebrew 的软件管理方法，显著提升在苹果系统下的开发与运维效率。 老Mac用户应该都有过这种经历：想装个wget、node或者ffmpeg，去官网一看，要让源码编译，依赖一个接一个，半天都装不完；直接下载dmg安装包吧，遇到升级版本的时候，又得重新手动下载一次。我第一次折腾Ruby环境的时候，就是在源码编译上浪费了一下午，后来同事甩过来一句“你别手动折腾了，用Homebrew装”，我才开始接触这个macOS上的软件管理工具。
Homebrew是一款面向macOS和Linux系统的软件包管理器，通俗点说，它就是macOS的“应用商店”，只不过它管的不是图形界面的App，而是数万个开发者需要用到的命令行工具、运行环境和基础库。装了它之后，安装软件只需要敲一行命令，升级、卸载、管理依赖也都是自动化处理，不用再跟编译参数、动态链接库搏斗。这篇文章我会从核心概念、安装配置、日常操作到常见报错排查，把我自己这几年折腾Homebrew的经验完整写一遍，希望对刚入坑Mac或者刚接触命令行的读者有帮助。
1. 项目概述：Homebrew到底解决什么问题
1.1 一个包管理器为什么这么重要
先说说没有包管理器的时候，在macOS上装一个开发工具是什么体验。以安装nginx为例，你需要先去官网下载源码包，然后自己解决PCRE、zlib、OpenSSL这些依赖库，每一个库都可能因为版本问题跟你闹脾气，configure阶段报错、编译阶段报错、链接阶段报错，光是排错就能耗掉半天。更麻烦的是，以后想升级nginx，你还得把这些流程重新走一遍。
有了Homebrew之后就完全不一样了。它背后有一个庞大的社区维护的Formula仓库，把每个软件的下载地址、依赖关系、编译参数都提前定义好了。你执行一条brew install nginx，它会自动把依赖处理、下载、编译、目录安装、环境变量配置全搞定，整个过程是可控的、可重复的、可回滚的。
这也解释了Homebrew名字的由来：brew是酿造的意思，它把软件的“配方”叫Formula，软件的安装目录叫Cellar（酒窖），装好的程序像一瓶瓶酒一样整齐码在酒窖里。这种设计理念贯穿始终——一切管理都有章法，安装和卸载都干干净净。
1.2 Homebrew、MacPorts、手动编译怎么选
在macOS生态里，除了Homebrew，还有MacPorts和老牌的手动编译安装。我当年也纠结过，都试过一轮后，一直用到了今天的还是Homebrew。
- MacPorts：更像FreeBSD的ports体系，依赖库统一安装在/opt/local下，规则很严格，但编译速度偏慢，很多包需要从源码构建，而且占用空间比较大。
- 手动编译：适合需要对编译参数做非常定制化调整的场景，比如你要针对特定CPU架构做优化，但日常使用完全没必要付出这么高的时间成本。
- Homebrew：在“开箱即用”和“可控性”之间取了一个很好的平衡。它默认用预编译好的二进制包（也就是bottle）安装，速度很快，同时如果你想改编译参数，也可以直接编辑Formula定制安装。
简单说，绝大多数人日常使用选Homebrew就够了，不用折腾。
2. Homebrew核心设计思路与目录结构解析
2.1 四个关键目录：Cellar、Caskroom、bin、opt
要真正用好Homebrew，我建议先理解它在磁盘上是怎么组织文件的。Homebrew安装后，会在主目录下创建几个核心目录，我用一个表格说明它们的分工：
| 目录 | 作用 | 位置说明 |
|---|---|---|
| Cellar | 软件本体实际安装的地方，每个软件按版本路径存放 | /usr/local/Cellar（Intel）或/opt/homebrew/Cellar（Apple Silicon） |
| Caskroom | 存放通过brew install --cask安装的图形化App包 | 同前缀下的Caskroom目录 |
| bin | 存放命令行工具的软链接，指向Cellar里的真实可执行文件 | /usr/local/bin或/opt/homebrew/bin |
| opt | 存放需要被引用/关联的旧版本或不带前缀的软件路径 | /usr/local/opt或/opt/homebrew/opt |
我举个例子：你执行brew install python@3.11，Homebrew会先把Python 3.11装到Cellar下，然后在bin目录里生成一个python3.11的软链接，同时根据依赖关系把openssl、sqlite这些组件放到opt目录下。这样设计的好处是，多个软件可以共存不同版本，想切换时只需要调整PATH优先级。
2.2 Formula和Cask到底什么区别
这是很多人用Homebrew时最容易混淆的概念。简单一句话：Formula管命令行工具，Cask管图形界面App。
- Formula：比如nginx、git、node、redis这类底层软件。安装命令是brew install xxx，安装后进入的是Cellar目录，提供的是命令行接口。
- Cask：比如Google Chrome、Visual Studio Code、WeChat这类带图标的桌面应用。安装命令是brew install --cask xxx，安装后它其实帮你把dmg下载、挂载、拷贝到/Applications这些步骤全自动执行了。
我自己的使用习惯是：命令行工具一律用普通brew install安装，桌面应用也尽量用Cask管理，这样以后升级、卸载都有统一入口，不用一个一个手动去拖图标删App。
2.3 Homebrew为何选择Ruby作为核心语言
不少读者可能会问，一个包管理器而已，为什么要用Ruby写，而不是Python或者Go？这里有一段历史原因，但更关键的是它在设计上的取舍：Homebrew最早的实现者Max Howell是macOS上知名的Ruby开发者，在2009年前后，macOS默认自带Ruby环境，直接用Ruby写可以让用户在安装Homebrew时几乎没有任何额外依赖。后来虽然macOS不再自带Ruby了，但安装器也内置了一套精简的Ruby运行时，所以用户依然不需要自己装Ruby。
用Ruby写的好处是脚本灵活、表达力强，Formula文件读起来像配置文件一样清晰。缺点是自动化执行性能一般，但日常使用brew命令根本感觉不到瓶颈。
3. 从零开始安装Homebrew与国内源配置
3.1 安装前需要准备什么
在跑安装命令之前，有两件事要确认：第一，macOS版本不能太旧，Homebrew目前要求macOS Monterey（12）以上，Linux系统则需要有Ruby、curl等基础工具；第二，电脑上要装Xcode Command Line Tools，它是很多编译行为的基础环境。
如果没有装Command Line Tools，你在终端里执行brew命令时，系统会自动弹出安装窗口。当然，也可以手动先装：
xcode-select --install然后执行Homebrew官方安装脚本。不同芯片架构的安装路径略有差异，Apple Silicon机器默认安装在/opt/homebrew，Intel机器默认安装在/usr/local，安装脚本会自动识别。
3.2 国内镜像源配置的完整流程
安装时最让人头疼的就是下载慢。Homebrew官方脚本需要从GitHub拉取代码，而很多国内网络环境访问GitHub并不顺畅，导致安装过程卡很久。这时候我建议直接用国内镜像源安装。
以中科大源为例，先执行环境变量设置，再跑官方脚本：
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"设置好之后，再执行官方那个长命令，整个下载过程就会快很多。
装完之后，还有两个源需要配置：一个是homebrew-core（所有Formula的仓库），另一个是homebrew-cask（所有Cask的仓库）。如果你是直接从官方源安装完，可以事后通过git remote命令切换：
cd "$(brew --repo)" && git remote set-url origin https://mirrors.ustc.edu.cn/brew.git cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core" && git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git cd "$(brew --repo)/Library/Taps/homebrew/homebrew-cask" && git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git这里我提醒一句：镜像源只影响brew工具本身和软件包的下载，不影响你之后软件的使用。清华源、阿里源也都是类似思路，选一个离你近的就行。别同时配置多个源，反而容易出问题。
3.3 安装后的环境变量配置
安装完成后，Homebrew会提示你把核心入口加到PATH环境变量里。不同芯片架构的配置路径不一样：
- Apple Silicon：配置/opt/homebrew/bin
- Intel：配置/usr/local/bin
如果你使用zsh，通常在~/.zprofile里加一行：
eval "$(/opt/homebrew/bin/brew shellenv)"加完之后执行source ~/.zprofile，再运行brew --version看看是否显示版本号。如果显示出版本号，说明安装成功。
我遇到过不少新手卡在这一步，原因是PATH没配好，命令找不到。这时候别急着重装，先确认一下配置文件有没有写对。
4. Homebrew的日常基本操作详解
4.1 常用命令速查与使用心得
日常使用中，我真正高频用到的基础命令其实就那几个。整理成一个速查表：
| 命令 | 作用 | 使用示例 |
|---|---|---|
| brew search | 搜索软件包 | brew search nginx |
| brew install | 安装软件包 | brew install nginx |
| brew install --cask | 安装图形App | brew install --cask google-chrome |
| brew uninstall | 卸载软件包 | brew uninstall nginx |
| brew list | 列出已安装包 | brew list --versions |
| brew update | 更新Homebrew本身和Formula索引 | brew update |
| brew upgrade | 升级已安装的软件包 | brew upgrade |
| brew cleanup | 清理旧版本和下载缓存 | brew cleanup -s |
| brew doctor | 检查系统与Homebrew健康状况 | brew doctor |
这里分享两个我自己的使用心得。
第一个心得是，不要一上来就无脑brew upgrade全部升级。因为有些软件的高版本可能会破坏依赖兼容性，尤其像OpenSSL、Python这类底层库，升级后其他依赖它们的软件需要重新编译。我一般先在brew update之后，用brew outdated看看有哪几个包需要升级，然后一个一个升，避免一次把所有包都升了。
第二个心得是，想查看某个软件详细信息时，用brew info xxx能查出它的依赖、版本、安装状态、安装命令，排错时特别有用。
4.2 用brew services管理后台服务
Homebrew里还有一个容易被低估的功能：brew services。它能把MySQL、Redis、PostgreSQL这类需要常驻后台的服务管理起来，替代手动启动和kill进程的操作。
# 启动服务并设置为开机自启 brew services start redis # 停止服务 brew services stop redis # 重启服务 brew services restart mysql # 查看所有服务状态 brew services list这个命令的本质是把一个LaunchAgent配置生成了出来，交给系统来托管，所以才能真正做到系统重启后服务自动拉起。对开发机来说非常方便，不用再自己写daemon配置。
4.3 自定义tap：扩展软件仓库边界
Homebrew默认的homebrew/core仓库已经包含几万个软件了，但总有你需要的软件不在其中。这时候可以用brew tap来添加第三方仓库。最典型的就是homebrew/services（这个已经内置了）和homebrew/cask-versions，后者能让你安装多个版本的应用，比如安装Java 8、Python 2.7这类老版本。
brew tap homebrew/cask-versions brew install --cask java8如果你自己写了Formula，也可以传到自己的Git仓库里，然后通过brew tap别人下载。这是Homebrew生态能持续壮大的重要原因，它把软件定义做成了开放的Git仓库协作模式。
5. 安装报错、卸载残留与问题排查实录
5.1 安装过程中最常见的报错提示与对策
这里我整理几个我遇到过也帮别人排查过的高频报错，并附上处理思路。
报错一：curl: (7) Failed to connect to raw.githubusercontent.com port 443: Operation timed out
这是最经典的网络问题。原因就是安装脚本需要从GitHub的raw域名下载一个远程脚本，但网络连不上。解决办法我前面已经写了，用国内镜像源的环境变量再执行安装脚本，或者直接用带镜像地址的安装命令。
报错二：Error: Permission denied @ rb_sysopen - /usr/local/Homebrew
这种一般是权限问题。如果目录所有者不对，会导致Homebrew无法写入。解决办法是递归修改目录所有者：
sudo chown -R "$USER":admin /usr/local这个命令会把/usr/local目录的所有者改成当前用户，之后就不用每次sudo了。注意如果你用的是Apple Silicon机器，路径通常是/opt/homebrew，同样思路处理。
报错三：Error: The following directories are not writable by your user
这个和上面的情况类似。有的目录被安装包或系统占用，用sudo chown修复一下目录所有权就行。但如果你不确认当前目录是否安全，可以先用ls -ld /usr/local/bin看看所有者是谁，再决定改不改权限，避免误操作。
5.2 卸载Homebrew后老是清不干净怎么办
很多读者想知道“Homebrew卸载残留”怎么清理，其实Homebrew官方提供了卸载脚本：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"脚本会尝试删除Cellar、Caskroom、bin里的软链接等核心文件，但有些残留它并不会主动清，比如：
- 缓存目录：~/Library/Caches/Homebrew
- 日志目录：~/Library/Logs/Homebrew
- 服务配置：~/Library/LaunchAgents/homebrew.mxcl.*.plist
- 应用数据：~/Library/Application Support/Homebrew
如果确认不再需要，可以手动把这些目录删掉。但这里必须先说清楚，卸载脚本运行前，它会列出要删除的内容，你最好先看一眼，免得误删你自己手动创建的数据。
5.3 升级后软件损坏：架构与签名问题排查
我在Apple Silicon机器上遇到过升级后某个命令行工具突然提示“无法打开，因为无法验证开发者”的情况。这通常有两种原因：一个是软件没有做ARM架构适配，另一个是签名验证问题。
解决办法：先尝试用brew reinstall xxx强制重装该软件，让安装过程重新生成本地签名。如果还不行，检查它是不是需要Rosetta转译，Intel时代的很多老工具在ARM机器上需要安装Rosetta 2：
softwareupdate --install-rosetta装完之后，再用brew doctor检查一下，通常就能正常用了。
6. 进阶小技巧与个人经验补充
这部分算是我自己用得比较顺手、但很多教程不会仔细讲的几个点。
6.1 用brew bundle做开发环境一键部署
brew bundle能把当前机器上安装的所有Package和Cask导出成一个清单文件，换新电脑时直接一键安装，这个对开发环境迁移特别实用。
# 生成当前环境的Brewfile brew bundle dump --file=~/Brewfile # 在另一台机器上安装清单里的所有内容 brew bundle install --file=~/Brewfile这个文件本质是一个文本清单，可以提交到Git仓库里。我自己的做法是，每台工作电脑维护一个Brewfile，新配置环境时，先装Homebrew本身，再跑一遍brew bundle install，几分钟就把常用工具和App全部装回来了。
6.2 不要忽略brew doctor给出的警告
很多人把brew doctor当成可有可无的命令，其实它扫描的是整个Homebrew环境的健康状态，包括目录权限、symlink是否损坏、依赖是否一致、环境变量是否有冲突。我建议安装、升级之后都跑一遍，看到警告也别慌，它给出的提示一般都很直白，照着执行即可。
我在实际维护环境时，至少每个季度跑一次brew doctor，遇到Warning及时处理，久而久之就不会积累出大问题。
6.3 小心处理版本切换
如果你同时装了python@3.10、python@3.11这种多版本工具，Homebrew会自动在bin目录下生成带版本后缀的命令，默认命令则指向高优先级版本。如果你想固定使用某个版本，建议用brew link命令做版本切换：
# 让当前shell优先使用3.11 brew link python@3.11 --force --overwrite这条命令会把对应版本的工具链接进bin目录。但注意，--force参数会强制覆盖掉同名软链接，执行前最好确认一下你当前环境里哪些工具依赖旧版本，避免把已有环境搞乱。
我在实际使用中踩过一次坑：当时为了装一个老项目，把open ssl链回了1.1版本，结果其他好几个软件全部报动态库错误，只能一个个排查重装。后来学乖了，版本切换这种东西尽量在虚拟环境或容器里做，别全局折腾。
写在最后的一点体会
用了Homebrew这么多年，我最大的体会是：好的工具链应该让人“忘掉”工具本身，而不是整天跟工具作斗争。Homebrew之所以在macOS开发者中这么流行，不只是因为它安装命令一行搞定，更在于它的目录设计、依赖管理、升级策略都是有章法的，这让它在长期使用中变得非常可靠。
从第一次装Ruby时的束手无策，到后来用brew bundle在半小时内在新机器上恢复完整开发环境，Homebrew确实帮我节省了大量时间。如果你刚接触Mac开发，建议先把本文提到的基础命令亲手跑一遍，再慢慢研究tap、services、bundle这些进阶功能。等哪一天你发现自己在终端里敲brew install的时候一点犹豫都没有，就说明你已经真正上手了。
本文还有配套的精品资源，点击获取
