Mac安装Homebrew全攻略：官方脚本与国内镜像源

Mac 上装软件这件事我早期被折腾得够呛去官网下载 dmg拖进 Applications遇到更新还得重新下载覆盖。后来遇到 brew也就是 Homebrew才算是把 Mac 上的软件安装这件事真正理顺了。Homebrew 是 Mac 上最主流的软件包管理工具你可以把它理解成 App Store 的命令行版本但它能管的东西比 App Store 多得多——命令行工具、开发环境、图形软件、字体、甚至一些系统级组件它都能装、能更新、能卸载。这篇文章写给所有想在 Mac 上安装 brew 的朋友不管你是刚入行的开发者还是只是想把 Mac 用得更顺手我都会把安装流程拆开揉碎讲清楚包括官方脚本和国内镜像两种方案、环境变量配置、常见报错排查以及我用 brew 六七年踩过的那些坑。1. 为什么 Mac 需要 brew一个包管理工具的价值1.1 从 App Store 说起Mac 装软件的两种老路在 brew 出现之前Mac 用户装软件基本两条路。一条是去 App Store 搜索下载但 App Store 里的软件种类有限尤其开发者常用的命令行工具几乎没有另一条是去软件官网下 dmg 安装包双击挂载然后把图标拖进 Applications 文件夹。第二种方式看着简单但后续更新很麻烦——你得自己记住从哪下的隔几个月再去官网看有没有新版本下载覆盖安装操作重复度极高。更麻烦的是依赖问题。你想装一个工具它依赖另外三个库另外三个库又依赖更多底层组件。手动一个个装装到一半报错你甚至不知道错在哪。这在开发环境里特别常见装 Python、装 Node、装各种数据库每一个都有自己的一堆依赖。我在刚接触 Mac 开发时就曾经为了装一个 PHP 扩展手动编译了半个小时最后还因为缺了一个系统库直接失败。1.2 brew 到底能做什么从命令行工具到图形软件全覆盖brew 解决的就是上面这些问题。它会自己处理下载、依赖、更新、卸载你只需要记住几个简单命令。比如brew install git装 Gitbrew install mysql装 MySQLbrew install --cask google-chrome装 Chrome 浏览器。brew 本身分为两大块。第一块是 brew也就是 Homebrew 的核心用于管理命令行工具和开发库装完后文件通常存放在/opt/homebrewApple Silicon 芯片或/usr/localIntel 芯片目录下由 brew 统一管理你不用担心系统目录被搞乱。第二块是 Homebrew Cask用于安装图形界面的 macOS 应用它会自动下载 dmg 或 pkg 安装包帮你完成挂载、复制、卸载的全过程像 Visual Studio Code、Google Chrome、阿里云盘这类应用都能直接通过brew install --cask装好。另外 brew 还支持 Homebrew Services专门管理后台服务进程。比如你装了 MySQL 或者 Redis可以用brew services start mysql启动并设置开机自启再也不用去找什么mysql.server start或者手动写 launchd 配置了。1.3 什么人最需要 brew如果你属于下面任何一种情况brew 基本就是你绕不开的选择开发者需要安装和切换各种语言运行时、数据库、命令行工具设计师或效率用户经常需要下载安装各类效率软件希望有个统一的安装入口系统洁癖不想在系统里到处散落安装包残留文件希望卸载得干净彻底需要批量在多台 Mac 上复现同一套软件环境。我自己的 Mac 上现在有超过两百个软件包是通过 brew 管理的。从终端工具、字体、到图形软件全部统一管理重装系统后只需要一个brew bundle命令就能恢复大部分环境这种体验一旦用上就很难回去了。2. 安装前的准备先搞清楚这 3 件事2.1 你的 Mac 是 Intel 还是 Apple Silicon路径完全不同安装 brew 之前第一件事是确认自己 Mac 的芯片架构。因为 brew 的安装路径和配置方式在 Intel 和 Apple Silicon 上有明显差异。Apple Silicon 芯片M1、M2、M3、M4 系列的 Macbrew 会安装到/opt/homebrew目录Intel 芯片的 Macbrew 会安装到/usr/local目录。这两个路径差别很大因为/usr/local在 Intel 架构下通常是可写的而/opt/homebrew是 Apple Silicon 的专属目录。怎么查自己 Mac 的芯片点击左上角苹果菜单选择关于本机在芯片一栏就能看到。如果是 Apple M1、M2、M3、M4 这类字样就是 Apple Silicon如果是 Intel Core i5、i7 之类就是 Intel。这个区别很重要。网上很多安装教程写的都是/usr/local路径的老办法Apple Silicon 用户如果照着抄很容易在权限上卡住。后面我会详细讲这两种芯片在配置环境变量时的不同写法。2.2 Xcode Command Line Toolsbrew 的隐藏依赖brew 安装过程中最大的一个隐藏依赖是 Xcode Command Line Tools。这个工具集包含了 Git、clang 编译器、make 等一堆编译相关的命令行工具brew 在安装很多软件包时都会用到它们。好消息是brew 安装脚本会自动弹出 Xcode Command Line Tools 的安装窗口你只需要点确认然后等它装完。坏消息是这个安装过程比较慢视网络情况可能需要几分钟到十几分钟而且没有明显的进度条很多人在这里以为卡住了直接关掉窗口导致后续安装失败。如果你自己装强烈建议先单独手动安装 Xcode Command Line Tools避免 brew 安装过程中因为等待而超时。命令很简单xcode-select --install执行后系统会弹窗点击安装同意协议等它下载完成即可。安装完可以验证一下xcode-select -p如果输出类似/Library/Developer/CommandLineTools的路径说明已经装好了。顺便说一句Xcode Command Line Tools 和完整的 Xcode 是两回事。完整 Xcode 几个 GCommand Line Tools 才几百 M日常用 brew 只需要后者不要搞混。2.3 网络与下载源为什么很多人卡在第一步brew 安装脚本本身是从 GitHub 拉取的而 brew 后续安装软件时默认也要去 GitHub 等海外源下载。对于国内网络环境来说这就经常出现连不上、下载慢、中断的问题。很多人安装 brew 卡住十有八九是网络问题。所以安装前我建议你先想清楚自己要用哪种方式如果网络环境访问海外资源没问题用官方脚本直接装就行如果在国内网络环境下安装提前准备好国内镜像源。这里说的镜像源和某些特殊工具没有任何关系指的是中科大、清华、阿里云这些高校或云厂商提供的开源软件镜像站。它们把 brew 的安装脚本、软件包仓库、预编译二进制包同步了一份到自己服务器上国内访问速度就快很多。这也是完全合规的常规操作很多企业内部的软件分发也是这个思路。3. 安装 brew 的完整实操从零到帮着能用3.1 官方标准安装脚本最直接的路线如果你网络环境比较顺畅直接使用官方脚本是最简单的安装方式。打开终端Terminal输入下面这行命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这个命令的意思是用 curl 下载 Homebrew 官方安装脚本然后通过 bash 执行。执行过程中脚本会先检查你的系统环境提醒你即将安装的位置Apple Silicon 是/opt/homebrewIntel 是/usr/local还会检查 Xcode Command Line Tools 是否安装没装的话会自动触发安装。脚本执行到一定步骤会停下来等一个回车确认然后开始拉取 Homebrew 仓库。这一步就是最考验网速的时候如果迟迟没有动静或者出现了curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused这类报错说明网络连接 GitHub 失败了不用硬等直接切换国内镜像源方案。3.2 国内镜像源安装中科大、清华、阿里云方案国内镜像源安装 brew 的核心思路是先把 Homebrew 的安装脚本下载到本地然后把脚本里的官方源地址替换成国内镜像站的地址再本地执行。这样脚本就能从国内快速拉取所有需要的内容。我用得比较多的是中科大USTC的源镜像同步比较及时也很稳定。下面是完整的过程。首先设置镜像环境变量然后把官方安装脚本下载到本地并执行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 export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这里的四个环境变量含义分别是HOMEBREW_BREW_GIT_REMOTEHomebrew 主仓库的地址替换为中科大镜像HOMEBREW_CORE_GIT_REMOTEHomebrew 核心软件包仓库地址HOMEBREW_BOTTLE_DOMAIN预编译二进制包的下载地址这个最关键直接影响软件安装速度HOMEBREW_API_DOMAIN新版 Homebrew 的 API 数据接口地址用于查询软件信息。执行完这一套后面安装流程就和官方脚本一样只是所有网络请求都走了国内镜像速度会快非常多。整个安装过程如果顺利通常三五分钟就能完成具体时长看网速和芯片性能。如果你更习惯清华或阿里云的源也可以把上面中科大地址换成对应镜像站的地址思路完全一致。我这里以中科大为例子是因为我自己长期使用下来的下载速度和稳定性综合表现最好。3.3 安装后的关键一步配置环境变量安装完成之后终端会输出一段Next steps提示让你把 brew 加到 shell 环境变量里。这一步很多新手容易漏掉直接导致输入brew提示command not found。Apple Silicon 芯片的 Mac在终端执行echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 芯片的 Mac执行echo eval $(/usr/local/bin/brew shellenv) ~/.zprofile eval $(/usr/local/bin/brew shellenv)第一行命令是把 brew 的初始化配置写入用户的 zprofile 文件作用是每次打开终端时自动加载 brew 环境第二行是让当前终端立刻生效省的再开一个新窗口。这里的~/.zprofile是 zsh shell 的用户配置文件。macOS 从 Catalina 开始默认 shell 就是 zsh所以配的是 zprofile。如果你用的是别的 shell比如之前的 bash则可能需要写进~/.bash_profile。不太确定的话用echo $SHELL查一下自己的默认 shell 是什么就行。配置完成后验证一下是否安装成功brew --version brew -v能看到版本号说明 brew 已经可用了。我再顺手测一下安装软件是否正常比如装一个常用的命令行工具 wgetbrew install wget能正常下载安装说明镜像源配置也生效了。如果这里报错或者下载很慢多半是环境变量没写入或者镜像源没配好后面排查章节会细讲。3.4 安装完成后别忘了切回中科大源上面 3.2 小节里的环境变量是在执行安装脚本的终端临时生效的也就是说只对那一次安装过程有效。安装完成后如果你想以后安装其他软件也能走国内镜像需要把镜像源配置固化下来。新建终端执行echo export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api ~/.zprofile echo export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles ~/.zprofile echo export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git ~/.zprofile echo export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git ~/.zprofile source ~/.zprofile然后执行brew update把仓库源信息同步一下brew update这一步会拉取最新软件包索引走的是国内镜像正常情况下很快就完成。到这里brew 的安装和国内源配置就全部结束了可以正常使用了。4. 装完之后怎么用常用操作与日常维护4.1 高频命令安装、卸载、查找软件包brew 的核心命令并不多背住这几个就能覆盖九成使用场景命令作用示例brew search 名称搜索软件包brew search mysqlbrew install 包名安装命令行软件brew install gitbrew install --cask 包名安装图形界面应用brew install --cask google-chromebrew list查看已安装软件brew listbrew uninstall 包名卸载软件brew uninstall wgetbrew update更新 brew 本身和软件源索引brew updatebrew upgrade升级所有已安装软件brew upgradebrew info 包名查看软件详情brew info mysqlbrew services start 服务名启动后台服务并设置开机自启brew services start mysql刚上手时最容易搞混的是普通安装和 cask 安装的区别。简单记命令行工具用brew install图形界面 App 用brew install --cask。比如装 MySQL 数据库用普通安装装 Navicat 这样的数据库管理界面软件就要加--cask。举几个开发环境里常用的真实例子。装 JDK 8brew install --cask temurin8装 Maven 并配置环境brew install maven mvn -version装 Python、Anaconda、Gitbrew install python git brew install --cask anaconda一键装好这些比去官网一个个下安装包省事太多而且后续升级只需要brew upgrade一条命令系统路径里也不会残留一堆版本混乱的文件。4.2 Cask 的使用细节管理图形软件的正确姿势Cask 是 brew 的一大杀器也是很多人容易忽略的部分。通过brew install --cask安装的图形应用会被统一管理在/Applications目录下和平时手动拖入的 App 一样出现在启动台里。卸载 Cask 应用时brew uninstall --cask 包名会把 App 本体和相关的偏好设置文件一起清理比手动把 App 拖进废纸篓干净得多。我用这个命令卸载过不少软件对比下来残留文件确实少很多。有的 Cask 应用还支持强制安装比如--force参数。某个 App 你之前手动装过又用 brew 再装一遍时可能提示已存在不想留着旧的就加--forcebrew install --cask --force google-chrome另外提一句brew 本身没有官方 GUI 客户端但有几款第三方工具做得还不错比如一些开源项目会把 brew 的常用操作封装成可视化的界面方便不熟悉命令行的用户。不过就我个人体验而言命令行用久了反而更顺手毕竟一个brew upgrade就打完了没必要再开一个程序窗口。4.3 卸载 brew想干净移除怎么办brew 用了一阵子想卸载的情况也有比如你想全部重来。官方提供了卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)脚本会扫描并删除 brew 安装的所有软件包、缓存文件、日志以及自身目录。执行前它会列出将要删除的文件清单让你确认一次。确认后/opt/homebrew或/usr/local下的内容会被整体移除之前通过 brew 装的软件自然也就没了。要注意的是卸载 brew 后它安装的命令行工具和 Cask 应用也会一并删除如果有需要保留的数据先备份好。另外如果你给 brew 配过镜像源环境变量就是在 zprofile 里写的那些 export 行卸载后也可以顺手删掉保持 shell 配置干净。5. 常见问题与排查实录5.1 安装卡住或报错443、curl、权限问题我在帮朋友装 brew 的过程中遇到过太多安装失败的案例绝大多数都是下面这几个问题第一种是curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused或者curl: (28) Operation timed out。这是下载官方安装脚本时连接 GitHub 失败。解决方案就是换成国内镜像源方案直接把脚本下载后配合镜像站环境变量执行。如果你已经在执行过程中卡住Ctrl C终止掉然后从 3.2 节重新开始就行。第二种是Error: /opt/homebrew is not writable或者Permission denied的报错。这种情况多半是因为系统给/opt/homebrew目录设了权限限制或者你之前安装时中断导致目录归属错误。解决方法是把目录权限改回给当前用户sudo chown -R $USER:admin /opt/homebrew执行后再重新运行安装脚本。Intel 芯片的话把路径换成/usr/local即可。第三种是安装过程中卡在 Tapping homebrew/core这一步不动。这种情况大多是网络问题GitHub 仓库拉取卡住了。解决办法还是走镜像源或者直接中断后重新配好镜像环境变量再执行安装。5.2 装完用不了command not found 和源切换失效安装成功但输入brew提示command not found不用怀疑就是环境变量没有生效。回到 3.3 节检查一下~/.zprofile文件内容cat ~/.zprofile如果里面没有eval $(/opt/homebrew/bin/brew shellenv)这一行说明之前写入失败了或者你写的路径不对。Apple Silicon 的 brew 路径是/opt/homebrew/bin/brewIntel 的是/usr/local/bin/brew别搞混。补上之后source ~/.zprofile即可。还有一种情况是 brew 能用了但下载软件还是慢这多半是镜像源环境变量没配到 shell 配置文件里。你在当前终端手动 export 的环境变量关闭窗口就失效了下次新开的终端还是走默认官方源。解决方法是把 export 写进~/.zprofile方法看 3.4 节。5.3 安装时间太长或卡住不动耐心和策略很多人关心 brew 安装到底要多久。这里我给个参考如果 Xcode Command Line Tools 已经装好网络顺畅的情况下Apple Silicon 芯片安装 brew 本体通常三五分钟就完事但如果 Xcode Command Line Tools 需要现场安装再加上网络一般整个过程可能拖到十几分钟甚至更久。卡住不动有两种情况。一种是真的卡死了比如网络测试通不过导致脚本反复重试另一种只是看起来卡其实在后台下载大文件没显示进度。判断方法是看终端是否还在持续输出输出或者用ps aux | grep install看看相关进程是否还在跑。超过十分钟没任何动静大概率有问题果断中断重来别傻等。换个工作目录、换网络比如手机热点经常能解决网络不稳定导致的下载中断。5.4 排查速查表把问题一次看明白报错现象常见原因解决方法curl: (7) Failed to connect...GitHub 连接失败使用国内镜像源安装curl: (28) Operation timed out下载超时换网络、重试、走镜像源/opt/homebrew is not writable目录权限问题sudo chown -R $USER:admin /opt/homebrewcommand not found: brew环境变量未配置写入 zprofile 并 source卡在 Tapping homebrew/core仓库拉取失败配置镜像源后重试下载软件慢镜像源未生效把镜像环境变量写入 zprofile安装软件时要求输入密码正常权限请求输入 Mac 开机密码这个很常见不用慌5.5 一些经验和建议最后说点实际的。第一刚装完 brew 时不要急着装一堆软件。先只装一两个跑通流程确认镜像源稳定、环境变量没问题再批量安装其他软件。第二定期执行brew update brew upgrade。我习惯每周跑一次把 brew 本体、软件源索引、已安装的软件整体升级一遍。别等出了问题才想起来这回事。第三善用brew doctor。它是最实用的体检命令输入后 brew 会检查自身配置和环境列出所有异常点比如目录权限不对、有重复的软件、环境变量冲突等。装完 brew 后先跑一次brew doctor看起来输出全是英文但大多意思明确照着提示处理就行。第四如果你在一台新 Mac 上想快速复现原来那台机器的软件环境用brew bundle。在旧机器上执行brew bundle dump生成一个 Brewfile 文件拷贝到新机器后执行brew bundle install所有软件都会自动装回来。我这两年换机、重装系统全靠这个文件省了太多时间。踩过的坑多了也就有了经验。brew 这东西本质上只是一个包管理工具但用好了它能让你的 Mac 变得极度顺手——软件安装统一入口、升级一条命令、卸载干净利落、环境复制几乎零成本。不管你是开发者还是普通用户只要愿意在终端里多敲几行命令它回报给你的效率提升是实打实的。