简介Homebrew 是 macOS 上备受推崇的开源软件包管理工具面向需要高效管理开发环境的 Mac 用户系统解决命令行工具与图形应用的安装、更新和卸载难题。资源包共包含 2000 个文件以 Ruby 脚本.rb、Markdown 文档、YAML 配置、JSON 数据等为主其中 rb 文件是 Homebrew 的配方定义md 与 yml 分别承载说明文档和配置信息压缩包整体约 421.56MB结构完整、便于检索适合从入门到进阶的开发者与运维人员系统研读。内容从一行命令安装、brew 基础操作讲起深入解析 /usr/local 下的 Cellar、Library、bin 等目录结构与工作原理同时介绍 Homebrew Cask 管理 Chrome、VS Code 等 GUI 应用自定义 tap 获取第三方软件以及 brew doctor、brew cleanup 维护清理技巧和常见问题排错策略能够帮助读者建立从安装配置到日常维护的完整知识闭环。已有 21672 人学习下载无论初学者还是老手都能借此快速掌握 Homebrew 的高效用法搭建更流畅的 Mac 开发环境。1. 为什么 macOS 用户几乎绕不开 Homebrew先聊点实在的。用过 macOS 一段时间的人早晚会遇到这样的场景想装个 wget、ffmpeg、git 的某个新版本或者某个命令行小工具但系统自带的版本太老去官网下载又找不到合适的安装包。Windows 上有各种一键安装的 exeLinux 有 apt 或 yum唯独 macOS 卡在中间——图形化安装包不少但命令行生态始终缺一个真正好用的包管理器。Homebrew 就是来填这个坑的。它官方自称 The Missing Package Manager for macOS翻译过来就是macOS 缺失的那个包管理器。这个名字起得很妙因为它某种意义上补全了 macOS 作为类 Unix 系统却不像 Linux 发行版那样自带包管理的短板。我第一次用 Homebrew 是好几年前当时只是想装个 Python 版本管理工具没想到这一用就离不开了。到现在我所有 Mac 上的开发环境、常用小工具基本都是通过 Homebrew 统一管理的。装什么、卸什么、升级什么一条命令搞清楚比在图形界面里一个个找安装包、拖拽到 Applications、再手动清理残留不知道省了多少事。这篇内容适合谁两类人。一类是刚开始用 Mac、想折腾开发环境但不知道从哪里入手的萌新另一类是已经用了一阵子 Homebrew 但遇到安装报错、卸载残留、下载速度慢等实际问题想系统搞清楚原理的老用户。我会把自己踩过的坑、排查过的报错、摸索出来的国内源配置方案都整理出来尽量少讲没用的理论多给能直接抄作业的操作。2. 完整安装流程从官方脚本到国内源加速2.1 官方脚本安装的完整步骤先说明一下当前2025 年前后主流的安装方式。Homebrew 官方推荐用一条命令直接安装在终端里执行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这条命令会把 Homebrew 装到/opt/homebrewApple Silicon 芯片或/usr/localIntel 芯片同时安装 Command Line Tools for Xcode。整个过程需要几分钟期间需要输入一次密码这是为了给目录设置正确的权限。但问题是国内网络环境下这条命令经常卡住或者直接报错。我身边十个装 Homebrew 的起码五六个第一次都失败了。原因出在几个环节raw.githubusercontent.com 域名被干扰、下载 Command Line Tools 速度极慢、安装过程中龟速甚至超时。所以很多人的第一步不是装 Homebrew而是先跟网络问题搏斗。2.2 安装报错的常见原因与处理顺序结合我自己的经历和帮别人排查的情况安装失败通常集中在以下三种网络阶段失败报错信息通常是curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused。这不是你操作错了是域名访问受限。处理办法是换国内镜像安装脚本下面 2.3 会详细写。Command Line Tools 下载失败报错可能是Error: The Command Line Tools header package must be installed on the system或卡在下载阶段很久不动。这种情况如果网络没问题可以先用命令手动安装xcode-select --install弹出图形化窗口后确认安装等它跑完再重新执行 Homebrew 安装脚本。权限或系统版本不符比如提示Error: Your macOS version is too old说明系统版本过低Homebrew 官方支持的 macOS 版本有下限太老的系统确实装不了新版本的 Homebrew。这个没什么好办法要么升级系统要么用旧版本 Homebrew 分支但后者维护成本高不建议普通用户折腾。2.3 国内镜像安装靠谱方案实测既然官方路径慢国内镜像就是最现实的方案。目前常用的镜像源包括中科大USTC、清华TUNA和阿里云。以中科大镜像为例安装 Homebrew 分为三步走第一步安装脚本替换为镜像脚本export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这里先设置三个环境变量目的是告诉安装脚本git 仓库和预编译包bottle都从国内镜像拉取。设置完再执行官方安装脚本脚本本身还是从 GitHub 拉取但这个路径通常是可以访问的实测下来成功率比直接官方安装高得多。第二步验证安装结果装完后执行brew -v能看到类似下面的输出Homebrew 4.x.x Homebrew/homebrew-core (git revision xxxx; last commit xxxx)同时可以执行brew doctor它会检查当前安装的整体健康状况提示哪些地方需要修复。这里有个细节很多人装完之后第一件事就是brew install但建议先跑一下brew doctor如果有权限问题或者路径问题这个时候发现是最省事的。第三步后续源配置那三个环境变量在安装完成后就失效了以后每次更新 Homebrew、安装软件时还会走 GitHub 官方源速度还是会慢。解决方法是写入 shell 配置文件zsh 用户是~/.zshrcbash 用户是~/.bash_profileecho export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git ~/.zshrc echo export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git ~/.zshrc echo export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles ~/.zshrc source ~/.zshrc这样设置之后后面安装、更新依赖包时都会优先走国内镜像速度从几分钟还转圈变成几秒钟跑完体感差别非常明显。注意HOMEBREW_BOTTLE_DOMAIN 这个变量控制的是预编译二进制包的下载地址。Homebrew 默认会优先下载 bottle 而不是从源码编译bottle 就是各家 CI 编译好的二进制包省去了本地编译的时间。镜像源配置好了bottle 下载快安装速度自然快。3. 核心操作拆解install、uninstall、update、search 一次讲透3.1 install 背后发生了什么装 Homebrew 只是开始日常使用频率最高的命令其实是brew install。比如brew install wget brew install ffmpeg brew install nginx很多人用了一辈子这条命令但不知道它背后做了三步事。了解这个过程对排查问题非常有帮助。第一步解析依赖。Homebrew 每款软件都有 Formula安装配方里面写明了依赖哪些库、需要什么编译选项。比如ffmpeg这个包依赖几十个库如果你从源码编译整个装完可能得一两个小时。但绝大多数情况下你不需要等这么久因为有第二步。第二步拉取 bottle预编译二进制包。Homebrew 会先从 Formula 定义里找到当前系统版本对应的 bottle然后直接下载解压。这就是为什么只要网络不差brew install通常一两分钟内就能完成。bottle 匹配的逻辑是软件版本 macOS 版本 CPU 架构比如ffmpeg的 bottle 会匹配你用的是 Apple Silicon 还是 Intel 芯片。第三步处理依赖和链接。下载解压完成后Homebrew 会把可执行文件软链接到/opt/homebrew/bin这个目录同时安装依赖库。所以你在终端里能直接用wget命令就是因为/opt/homebrew/bin在你的 PATH 环境变量里。理解了这三步就能明白两个常见的问题现象为什么有些软件安装特别慢大概率是它没有提供当前系统的 bottle只能走源码编译编译过程会输出大量日志终端里一行行滚。这种情况可以试试brew install --force-bottle 软件名强制只认 bottle没有就直接报错省得干等。为什么装 A 软件时会把 B 软件也一起装/升级这是依赖解析的结果Homebrew 默认会把依赖装到最新版本有时候会连带升级一些共享库比如 openssl、python 之类。遇到这种情况别慌这是正常行为。3.2 uninstall 与卸载残留问题卸载软件的命令brew uninstall 软件名比如brew uninstall wget。这个命令会卸载软件本身和它独有的依赖。这里注意一个点Homebrew 默认不会删除那些被其他软件共享的依赖所以有时候卸载了一个软件后执行brew autoremove还能清掉一批不再被任何软件引用的依赖包。我自己有个习惯每隔一阵子跑一遍brew autoremove brew cleanupautoremove清理孤儿依赖cleanup清理旧版本的下载缓存。之前我装过不少软件又卸载这两个命令每次都能帮我清出几百 MB 甚至上 GB 的磁盘空间。关于热词里提到的Homebrew 卸载残留我的看法是这样的Homebrew 本身卸载得还算干净真正的残留往往来自软件本身——配置文件、缓存目录、偏好设置这些。brew uninstall只负责卸载程序和库不管配置目录。比如卸载 mysql、nginx 这类服务型软件数据目录和配置目录是保留的。要知道 Homebrew 装的东西放在哪、哪些需要手动清理基本就靠两个路径/opt/homebrewApple Silicon或/usr/localIntelHomebrew 自身的安装目录/opt/homebrew/etc或/usr/local/etc配置文件目录卸载软件后可能有残留3.3 update 和 upgrade 的区别这两条命令非常容易被混淆。很多人以为brew update就是升级软件其实不是。brew update这是更新 Homebrew 自身的仓库元数据——也就是从远程 git 仓库拉取最新的 Formula 列表让 Homebrew 知道现在有哪些软件的新版本可用。它不升级任何已安装的软件。brew upgrade看包名升级到最新版本。可以接软件名也可以不接不接就是全部升级。brew upgrade wget brew upgrade --all实际使用建议定期执行brew update brew upgrade保持 Homebrew 元数据和软件都是最新的。但要注意升级所有软件可能带来兼容性问题尤其是某些依赖性的开发工具比如 Python、Node、OpenSSL 这类底层组件。如果升级后某个软件不能用了可以用brew list --versions 软件名查看当前版本再决定是降级还是排查问题。3.4 search 与 info安装前先摸清底细装东西之前先查一查能省掉很多麻烦。两条命令brew search 关键词 brew info 软件名brew search会从 repository 里检索匹配的 Formula找出所有包含关键词的软件包。有时候你会看到同名但后缀不同的包比如mysql和mysql-client、mysql5.7。这种就是不同版本或不同组件要按需选择。brew info会展示一个包的详细信息包括当前版本、依赖项、是否安装了、瓶装bottle是否匹配、安装路径等。我每次装不熟悉的软件前都会先跑一下brew info看看它依赖什么、有没有默认安装配置避免装完才发现不是自己想要的。4. 国内源配置解决下载慢、更新卡死的实际问题4.1 为什么镜像源不是可选项而是必选项在国内网络环境下Homebrew 的大部分卡顿都来自 GitHub。你会发现一个规律刚装好 Homebrew 的机器前几次brew install经常要等很久但如果用的是已经配置好国内源的机器基本输入完命令几秒钟就开始下载了。问题就出在默认情况下Homebrew 的相关请求都指向 GitHub 的仓库和发布页。如果访问 GitHub 不稳定那么你体验到的就是安装超时、brew update卡在remote: Enumerating objects不动、下载 bottle 速度只有几 KB/s。这不是 Homebrew 本身的问题纯粹是网络链路的问题。所以对我来说镜像源配置不是锦上添花而是装完 Homebrew 之后必须做的一步。不配置你很可能在一个月的某个晚上跟它搏斗几个小时。4.2 各镜像源方案对比我亲自测过中科大、清华、阿里云三个源简单说说感受镜像源更新频率速度表现稳定性备注中科大 (USTC)高快稳文档齐全推荐首选清华 (TUNA)高快稳同样很成熟备选阿里云中较快较稳偶尔有更新延迟个人用下来中科大和清华源都很成熟更新及时选哪个都行。如果你不确定选哪个直接用中科大社区口碑普遍较好。4.3 让配置长期生效前面 2.3 已经写了安装时的环境变量这里补充一下日常使用中如何让镜像长期生效。以中科大为例子编辑~/.zshrc确认自己的 shell 是 zsh最新的 macOS 默认就是export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles注意现在新版 Homebrew4.x增加了 API 模式默认从formulae.brew.sh/api拉取软件元数据这个地址在国内访问同样不稳定。所以除了配置 git 仓库和 bottle 下载源之外还需要设置HOMEBREW_API_DOMAIN环境变量。老教程经常漏掉这一项导致brew search和brew info反应很慢因为它们在走 API 拉取元数据。设置完之后重新加载配置source ~/.zshrc然后跑一遍brew update验证速度。如果几秒钟内完成说明源配置生效了。之后再执行brew install任何软件速度都会有质的提升。提示网上有些教程建议把整个 Homebrew 目录替换成 gitee 镜像或者用第三方脚本切换源。我的建议是尽量用官方支持的镜像源而不是依赖某个个人维护的脚本毕竟 Homebrew 版本迭代很快第三方脚本维护不及时容易出现兼容性问题。4.4 切换源后可能遇到的坑切换源不是一劳永逸的我遇到过两个典型问题git remote 分支指向混乱。这是切换源时最常见的坑。如果之前 Homebrew 的 git remote 指向 GitHub现在改成中科大执行git remote -v查看会发现 origin 已经变成镜像地址了。但有时旧的 remote 信息残留导致 fetch 报错。处理方法cd /opt/homebrew git remote -v如果 remote 地址不对手动改git remote set-url origin https://mirrors.ustc.edu.cn/brew.git更新源后提示版本不匹配。之前用旧版 Homebrew 拉取过元数据新源更新频率不同偶尔会出现本地缓存与远端不一致的情况。先试试brew update-reset这个命令会重置 Homebrew 的 git 状态清空本地元数据重新从远端拉取。跑完再brew update一般能解决。5. 卸载 Homebrew 与残留清理的正确姿势5.1 官方卸载脚本如果你真的决定不再用 Homebrew官方提供了卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)这个脚本会移除 Homebrew 的程序目录、缓存、日志和一些符号链接。实测下来大部分核心内容都会被清理掉。但卸载脚本跑完就干净了是一个常见误解。脚本重点是清理/opt/homebrew目录本身但安装过的软件可能在其他地方留下了痕迹。这也是热词里Homebrew 卸载残留被大量搜索的原因。5.2 哪些残留需要手动清理配置目录残留像我前面提到的brew install的软件配置可能写在/opt/homebrew/etc或/opt/homebrew/var卸载 Homebrew 时这些目录是跟随主目录一起删除的所以问题不大。真正需要手动关注的是那些软件自己生成的配置比如~/Library/Application Support/下的软件数据目录~/Library/Preferences/下的偏好设置 plist 文件~/Library/Caches/下的缓存目录这些目录里的内容卸载脚本不会动。如果你装过很多图形界面软件或用 Homebrew 装过服务型软件这里大概率有残留。用户级目录Homebrew 安装的服务比如brew services start nginx如果有自启动配置会写到~/Library/LaunchAgents/下。卸载前最好先停掉服务brew services stop --all环境变量残留如果你在~/.zshrc里配置过 Homebrew 相关的环境变量比如 HOMEBREW_BOTTLE_DOMAIN 或者把/opt/homebrew/bin加入 PATH卸载后这些配置还留在文件里虽然不影响系统运行但干净起见建议手动删掉。5.3 手动排查残留的通用方法不记得装过哪些服务型软件可以用以下命令排查ls ~/Library/LaunchAgents/ | grep -i homebrew ls ~/Library/Application\ Support/ | grep -iE (名称关键词)如果你很早就装了 Homebrew 且用得很频繁卸载前先列一下已安装清单方便对照brew list --formula brew list --cask--cask管的是图形界面应用这类应用的卸载残留和 Homebrew 本身的关系比命令行工具更明显如果你的 cask 软件没有用 cask 方式卸载而是直接拖到废纸篓那残留会更多。6. 后续还能怎么玩brew services 与 cask 的扩展用法Homebrew 常用操作讲完了再分享两个让它的价值翻倍的方向。第一个是brew services用 Homebrew 管理后台服务。比如你装了 mysql、nginx、redis 这类需要常驻运行的服务手动启动和管理进程很麻烦。brew services让这一切变得简单brew services start mysql brew services stop mysql brew services restart redis brew services listbrew services list能显示所有通过 Homebrew 安装的服务当前运行状态是启动、停止还是已注册。这个命令让我彻底告别了手动搞 launchctl 的日子也让我少记了一半命令行。第二个是brew install --cask用 Homebrew 管理图形界面应用。之前我说 Homebrew 管命令行工具这是它最核心的用途但 cask 扩展了边界——你现在可以用命令安装 Chrome、Visual Studio Code、微信等 GUI 应用brew install --cask google-chrome brew install --cask visual-studio-code brew install --cask wechat装完之后的效果和从官网下载安装包、拖进 Applications 是一样的但好处是你可以用命令升级、查看版本、统一卸载不再需要手动去官网下载、比对版本号。我个人现在的习惯是能用 brew cask 装的应用绝对不手动去官网下载。更新软件时只需要brew upgrade --cask --greedy它会检查所有 cask 应用是否有新版本有就一起升级。省事程度不是一星半点。不过 cask 也有个容易踩的坑有些应用提供了多个版本或者企业定制版用 brew cask 装的可能不是你要的那个版本。比如 Chrome 的 cask 版本就是稳定版想要 Beta 版还得去官网。这类细分化需求cask 默认并不覆盖需要自己加 tap 或手动处理。7. 我遇到的几个疑难问题与最终解法最后分享几个我实际踩过的坑和排查思路希望能帮你省下一些折腾时间。问题一更新 Homebrew 时卡在 Updating... Hack有一次执行brew update终端一直停留在Updating Homebrew...十几分钟没动静。排查时我先确认了是网络问题还是 git 锁问题。按 CtrlC 中断后执行ps aux | grep git发现有一个 git 进程长时间挂着kill 掉之后重新brew update还是卡。这时想起了 git 锁的问题——某个 git 操作异常中断锁文件没有释放。处理方式cd /opt/homebrew find . -name *.lock -type f把找到的 lock 文件删掉再brew update就正常了。问题二安装某个软件时提示 permission denied这在新手用户中特别常见因为早期版本 Homebrew 装在/usr/local目录系统文件权限严格普通用户没有写入权限。新版本装在/opt/homebrew通常情况下权限是没问题的。如果遇到权限报错先检查目录所有权ls -ld /opt/homebrew sudo chown -R $(whoami) /opt/homebrew把/opt/homebrew的所有者改回当前用户一般就能解决。不建议直接用sudo brew install这会让 Homebrew 管理的文件权限混乱后面会连锁报错。问题三brew install 下载速度很慢但检查镜像源又配置好了有一次装 PostgreSQL下载速度依然缓慢。后来发现这个包体积很大几百 MB而且某些大软件在镜像源上没有对应的最新版本 bottleHomebrew 回退到了 GitHub 官方发布页下载。解决办法是确认镜像源的 bottle 版本是否和本地系统匹配brew config查看HOMEBREW_BOTTLE_DOMAIN是否生效同时确认系统类型与版本。如果不匹配可以临时指定镜像域export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles brew install postgresql如果还是走 GitHub考虑等几天镜像源同步或者手动下载 bottle 文件本地安装。这个属于少数情况但知道了就有应对思路。我自己折腾了这些年 Homebrew最大的感受是它是一个工具但没有网上说的那么一装永逸。安装只是开始理解它的工作方式、学会排查问题才能真正用好它。希望这篇内容能帮你少走一些弯路。本文还有配套的精品资源点击获取