Mac安装HomeBrew全攻略：避坑、换源与报错排查

Mac 上装 HomeBrew表面上看是一条命令的事真正让人卡住的往往不是命令本身而是命令跑起来之后那一堆报错、下载卡死、权限不足、装完了brew还提示 command not found。我前后在五台机器上装过 HomeBrew有 Intel 的老 MacBook Pro也有 M 系列芯片的新机器中间踩过的坑基本覆盖了新手能遇到的全部类型。这篇就把 Mac 安装 HomeBrew 这件事从头到尾拆干净它到底是什么、为什么值得装、装之前要确认哪些前置条件、三种不同网络条件下的安装路径、装完之后怎么配国内源、常用命令怎么用、报错怎么排查、用久了怎么清理残留。不管你是刚拿到第一台 Mac 的新手还是被raw.githubusercontent.com port 443折磨过的老用户都能在里面找到能直接照着敲的东西。1. HomeBrew 是什么Mac 上绕不开的包管理器1.1 用生活场景理解包管理器在做什么把 Mac 想象成一间刚交房的毛坯屋子系统自带的东西相当于开发商送的简装有墙有水电能住人但你想装个浴霸、加个净水器、换个智能门锁就得自己一趟趟跑建材市场。跑一次两次还行装二十样东西的时候你就会开始抱怨为什么不能列个清单一次性送到家。HomeBrew 就是那个帮你跑腿的采购员。你告诉它我要 Python、我要 Node、我要 wget它自己去官方仓库下载、校验、解压、放到统一的位置、把命令挂到 PATH 里装完还能告诉你装哪儿了。你不想要了一条brew uninstall就给你清干净不会像手动装那样在硬盘里留下三四个不知名的文件夹。这个角色在 Linux 世界里对应的是 apt、yum、pacmanWindows 上对应的是 winget、scoop、chocolatey。Mac 官方一直没提供同等能力的工具所以 HomeBrew 从 2009 年出现到现在基本成了 Mac 开发者的默认选择。截至我写这篇的时候它仓库里可用的 formula命令行工具和 cask图形界面应用加起来有几万条覆盖面从git、python、ffmpeg一直延伸到各种桌面软件。1.2 为什么 Mac 用户最后都会装它刚接触 Mac 的人常问一句Mac 不是有 App Store 吗为什么还要装这个答案很直接App Store 只管图形界面应用而且审核策略导致很多开发工具根本进不去。你开发时真正需要的东西比如指定版本的 JDK、MySQL、Redis、Nginx、ImageMagick、Pandoc全都不在商店里。还有个现实问题网上教程里贴的命令一大半默认你已经有 HomeBrew 了。教程写先brew install mysql你敲下去提示 command not found然后就得回头补这一课。所以与其说是要不要装不如说是什么时候装。早晚都得装。我自己的判断标准很简单只要你在 Mac 上做三件以上需要敲命令的事装 HomeBrew 的时间成本就能在两周内收回来。它对版本管理的支持也比手动安装靠谱得多——你手动下载的 Python 3.9 想升到 3.12基本等于重装一遍brew upgrade python一条命令就完事。1.3 装之前必须先确认的三件事第一件是芯片架构。Apple SiliconM1 及之后的芯片和 Intel 芯片的安装路径完全不同前者默认在/opt/homebrew后者在/usr/local。这个差异会直接影响后面所有配置搞混了会出现装了两个 HomeBrew命令互相打架的诡异现象。查架构的方法是在终端里敲uname -m返回arm64就是 Apple Silicon返回x86_64就是 Intel。第二件是系统版本。HomeBrew 对新系统支持最好太老的版本会被判定为 deprecated安装过程中会弹警告甚至直接拒绝。查版本sw_vers如果你还在 10.15 这类老系统上比较稳妥的做法是先升级系统或者在旧版 HomeBrew 的 tag 上做安装后者对新手不太友好容易半路卡死。第三件是命令行工具。HomeBrew 本身是个 Git 仓库安装过程中要调用 git 和编译工具链这些由 Xcode Command Line Tools 提供。没装的话安装脚本会自己触发下载但那个下载在国内网络下经常龟速甚至中断所以强烈建议提前手动装好。提示这三项检查加起来不到一分钟但能省掉后面至少一半的报错。我见过太多人跳过这步然后在一个完全没必要的问题上折腾一小时。2. 安装前的环境准备把地基打平2.1 Command Line Tools 的检查与安装先看有没有装xcode-select -p如果返回/Library/Developer/CommandLineTools或类似的 Xcode 路径说明已经有了如果提示xcode-select: error: invalid active developer path那就是缺。安装命令很朴素xcode-select --install敲下去会弹一个系统对话框点安装然后等。这里有个坑要提前说这个对话框偶尔会抽风点了安装之后进度条不动、或者弹窗一闪就消失但实际没装上。遇到这种情况别硬等先删掉可能存在的半成品目录再重来sudo rm -rf /Library/Developer/CommandLineTools xcode-select --install另外还有一种情况是系统提示该软件目前无法从软件更新服务器获得这通常是网络或者系统版本问题换网络环境重试或者去 Apple 开发者下载页面手动下载对应版本的 Command Line Tools 安装包需要登录 Apple ID。装完之后再敲一次xcode-select -p确认路径存在然后验证 gitgit --version能打印出版本号就说明地基打好了。这一步别省很多人后面安装 HomeBrew 报git: command not found或者 clone 到一半失败根子都在这里。2.2 网络环境与镜像源的前置判断HomeBrew 安装脚本默认会去拉两个东西安装脚本本身以及 HomeBrew 主仓库。这两步在国内网络下都可能非常慢慢到你以为卡死了。判断方法很简单先跑一条命令看看脚本能不能拉下来curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o /dev/null -w %{http_code}\n返回 200 说明畅通可以走官方路径返回 000 或者卡住不动就说明需要走镜像方案。我的经验是能等到就等别一上来就换源因为镜像源本身也可能过期或者不同步官方源永远是第一时间更新的。如果你确实需要换源思路有两种一是用别人写好的换源安装脚本二是先手动给 git 配置镜像再跑官方脚本。第二种可控性更强我后面会详细讲。注意不管用哪种社区脚本装之前一定把脚本内容读一遍。这类脚本要执行的是下载和覆盖系统目录的操作闭着眼跑是对自己机器不负责。用curl拉下来之后先cat一遍看清楚它改了哪些文件、写了哪些环境变量。2.3 目录方案选择/usr/local 还是 /opt/homebrew这是很多人忽略的一步但它决定了你后面几年用起来顺不顺。Intel Mac 上的 HomeBrew 按历史惯例装在/usr/local。这个目录本来归 root 所有所以老教程里会出现大量sudo chown -R $(whoami) /usr/local之类的操作本质是把系统目录的属主改给当前用户好让 HomeBrew 不用 sudo 就能写。这件事有争议因为它会影响该目录下其他软件的行为。Apple Silicon 上就干净多了HomeBrew 装在/opt/homebrew这个目录是 HomeBrew 自己创建的天然属于当前用户不需要任何权限调整。所以如果你是新机器恭喜你跳过所有chown相关的麻烦。会出问题的是第三类情况Intel Mac 上曾经装过一次旧版 HomeBrew后来系统重装或者迁移助手把文件带过来了于是/usr/local里残留了一堆半成品。表现是安装脚本报Warning: /usr/local/bin is not writable或者Error: /usr/local/Homebrew is not a valid git repository。这时候要先清理再装具体方法在第 5 节讲。3. 三种安装路径的完整实操3.1 官方一键脚本最短路径与它的代价网络通畅的情况下官方脚本就是最省事的/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)敲下去之后会有几轮交互。脚本会先把要执行的操作用文字列出来等你按回车确认然后开始 clone 仓库。这个过程根据网速可能从两分钟到二十分钟不等中途会有进度显示。这里提醒一句进度条长时间不动不代表死了git 在大仓库上是分阶段输出的有时候几分钟才刷新一次别急着 CtrlC。真的等不下去就先中断检查网络后再重来重复执行是安全的。Apple Silicon 机器在安装过程中会额外提示需要安装 Rosetta 相关组件因为部分 formula 还是 x86 版本。脚本会问你要不要装一般选是。装完之后脚本的最后一段输出非常关键它会告诉你下一步要做什么 Next steps: - Run these commands in your terminal to add Homebrew to your PATH: echo /Users/你的用户名/.zprofile echo eval $(/opt/homebrew/bin/brew shellenv) /Users/你的用户名/.zprofile eval $(/opt/homebrew/bin/brew shellenv)这段东西一定要照着执行。它做的是把 brew 的 bin 目录加进 PATH并让 shell 每次启动时重新加载环境。跳过这步的话你新开一个终端窗口敲brew就会得到zsh: command not found: brew然后开始怀疑人生。3.2 国内镜像脚本把下载速度拉回来如果官方脚本卡在 clone 阶段走镜像是最现实的方案。我通常推荐两条路。第一条是先用镜像加速环境变量再跑官方脚本。在跑安装命令之前先导出这几个变量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然后再执行官方安装脚本。这样脚本内部 clone 的时候会走镜像地址速度能提上来。清华的 TUNA、中科大 USTC、阿里云的镜像都可以用把上面 URL 里的域名换掉即可。这几个源我都用过稳定性差异不大选一个离家近的就行。第二条是社区维护的一键换源安装脚本。这类脚本会把镜像配置、PATH 设置、环境变量一次性做完适合完全不想折腾的人。但我还是那句话先读脚本。有些脚本会往~/.zshrc里塞一堆东西某些变量和你已有的配置冲突事后排查起来很烦。装完镜像版本之后有一件必须做的事验证它真的在工作。执行brew update如果输出里显示的仓库地址是镜像域名说明配置生效了如果还是 github.com说明某个环境变量没写进 shell 配置文件只在当前会话临时生效了。这也是新手最容易忽略的一点——export只在当前终端窗口有效关掉窗口就没了要长期生效必须写进~/.zprofile或~/.zshrc。3.3 手动解压安装网络最差时的兜底方案还有一个终极方案把安装脚本和 HomeBrew 仓库都用别的方式弄到本地再手动执行。步骤是先用浏览器打开 HomeBrew 的 install 仓库页面找到install.sh下载下来同时把 brew 主仓库打包下载。然后在本地跑/bin/bash install.sh脚本检测到本地条件后会尝试 clone这时候可以配合前面说的环境变量把它指向镜像。整个思路是绕开脚本里那段最脆弱的网络请求把不可控因素降到最低。我必须说明这条路径操作步骤最多、最容易出错一般只在前两条都失败的情况下才用。如果你属于这种情况建议先把错误信息贴出来查一查往往问题不在网络本身而在代理设置或者 DNS 上。3.4 装完之后的验证与目录结构解读装完先验证brew --version brew doctor第一条打印版本号第二条是自检。brew doctor的输出值得认真读它会告诉你 PATH 是否正常、有没有重复安装、有没有权限问题。输出里出现Your system is ready to brew.是最理想的。如果它列了一堆 warning别慌大部分是提示性的按它给的建议逐条处理就行。然后是看一眼目录结构理解 HomeBrew 把东西放哪儿了对后面排查问题非常有帮助brew --prefix # 输出 HomeBrew 的根目录 brew --repo # 输出主仓库位置 brew --cellar # 输出所有已安装 formula 的存放目录以 Apple Silicon 为例brew --prefix是/opt/homebrewbrew --cellar是/opt/homebrew/Cellar。所有你装的东西都在 Cellar 里各自一个目录目录名带版本号。而/opt/homebrew/bin里是一堆软链接指向 Cellar 里的实际可执行文件。理解这层软链接关系很重要它解释了为什么升级某个包之后旧版本还能短暂共存也解释了为什么有时候删了 Cellar 里的目录会导致命令失效。4. 镜像源配置与日常基本操作4.1 四个仓库分别换源的方法HomeBrew 的镜像配置不止一个地方这点经常被搞混。实际上涉及四个部分组件作用配置方式brew.gitHomeBrew 自身的代码仓库git remote set-url 或 HOMEBREW_BREW_GIT_REMOTEhomebrew-core.git命令行工具的 formula 仓库git remote set-url 或 HOMEBREW_CORE_GIT_REMOTEhomebrew-cask.git图形界面应用的 cask 仓库git remote set-url 或 HOMEBREW_CASK_GIT_REMOTEbottles预编译好的二进制包HOMEBREW_BOTTLE_DOMAIN用 git 命令直接改远程地址的方式是这样git -C $(brew --repo) remote set-url origin https://mirrors.ustc.edu.cn/brew.git git -C $(brew --repo homebrew/core) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git git -C $(brew --repo homebrew/cask) remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git这样做的好处是配置写进了 git 的配置文件不依赖 shell 环境变量重开终端也生效。而用环境变量的方式则要写进~/.zprofileexport HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles export HOMEBREW_API_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles/api这里有个细节值得说新版 HomeBrew 大量使用 JSON API 来获取 formula 信息不再像以前那样完全依赖本地 clone 的仓库。所以如果你只改了 git remote 但没配 API 域名brew search这类操作依然会很慢因为它在拉 API。这就是为什么很多人换了源还是感觉没快多少——只换了一半。提示如果你只想做最小改动优先配HOMEBREW_API_DOMAIN和HOMEBREW_BOTTLE_DOMAIN这两个它们对日常体验的影响最直接。git remote 那部分在网络能勉强连通的情况下可以先不动。4.2 高频命令清单装好之后真正每天用的命令就那么十来个我按使用频率排一下brew install 包名安装命令行工具比如brew install wgetbrew install --cask 应用名安装图形界面应用比如brew install --cask google-chromebrew search 关键词搜索搜不到再用brew search --casksbrew info 包名看版本、依赖、安装路径排查问题的第一步brew list列出已安装的东西加--cask只看图形应用brew outdated看哪些包有新版本brew upgrade升级全部也可以指定单个包brew uninstall 包名卸载加--zap连配置文件一起删cask 才支持brew update更新 HomeBrew 自身和 formula 索引brew cleanup清理旧版本缓存这个后面单独讲有两个容易混淆的点brew update和brew upgrade不是一回事前者更新索引后者更新实际安装的软件。很多人以为跑了 update 就等于升级了其实没有。另外--cask装的东西和普通 formula 装的东西管理方式不同卸载时如果忘了加--cask会提示找不到包。4.3 一份可以直接抄的软件安装清单新机器拿到手我通常会一次性装一批基础工具省得后面一个个来。这套清单是我自己用下来最顺手的组合brew install wget curl git tree jq ripgrep fd brew install --cask google-chrome visual-studio-code iterm2wget和curl处理下载tree看目录结构jq处理 JSONripgrep和fd是搜索工具比系统自带的grep和find快很多也好用很多。图形应用那边按需增减就行。如果你还要做开发通常会在这一层继续叠brew install python node openjdk、brew install mysql redis。这里提醒一句用 HomeBrew 装 mysql 和 redis 之后它们不会自动作为后台服务运行需要手动启动brew services start mysql brew services listbrew services是个很实用的子命令它能帮你把服务注册成开机自启不用自己去写 launchd 配置文件。这是 HomeBrew 相比手动安装一个非常明显的优势。5. 报错排查实录那些让我卡住的瞬间5.1 常见报错速查表先把最常见的错误和对应处理列出来方便直接对号入座报错信息关键词大概率原因处理方向Failed to connect ... port 443到源站的网络不通换镜像源或检查本地网络与 DNSPermission denied dir_s_mkdir目标目录属主不对检查目录属主或改用其他 prefixxcrun: invalid active developer pathCommand Line Tools 缺失或路径失效重装 CLT必要时先删残留目录command not found: brewPATH 没配好执行 shellenv 写入配置文件is not a valid git repository半成品残留删掉残留目录后重装Another active Homebrew process is already running有 lock 文件残留找到并删除对应 lockCask is unavailable: No Cask with this name exists包名不对或 cask 索引未更新brew update后重试确认包名拼写git: unknown revision索引过期或分支名变更更新 HomeBrew或检查分支配置5.2 几个典型报错的完整排查过程先说那个最经典的 443 连接失败。报错长这样curl: (7) Failed to connect to raw.githubusercontent.com port 443 after 75000 ms: Couldnt connect to server它出现在安装脚本的第一步说明脚本本身都没拉下来。这时候先别急着换源用前面那条 curl 测试命令确认一下是彻底不通还是不稳定。如果不通直接走手动下载脚本加镜像的方案如果只是慢可以加大超时时间重试。我遇到过一种情况是本地 DNS 把域名解析到了错误的地址ping一下就能看出来换个 DNS 就好了。第二种是权限问题Error: Permission denied dir_s_mkdir - /usr/local/Homebrew这台机器上/usr/local的属主是 root而当前用户没有写权限。老教程会让你sudo chown -R $(whoami) /usr/local但我不太推荐这么干因为/usr/local下可能还有其他软件的文件整个目录改属主会带来副作用。更稳妥的做法是指定一个用户可写的目录作为 prefixexport HOMEBREW_PREFIX$HOME/homebrew export HOMEBREW_CELLAR$HOME/homebrew/Cellar export HOMEBREW_REPOSITORY$HOME/homebrew这样 HomeBrew 完全装在你的家目录里不需要任何 sudo。代价是某些依赖绝对路径的软件可能识别不到需要额外加 PATH。但作为兜底方案它比改系统目录属主要安全。第三种是两个 HomeBrew 打架。症状是brew --prefix的输出和你以为的不一样或者装完一个包之后which找不到。排查方法which -a brew echo $PATHwhich -a会列出所有匹配的可执行文件如果出现两个路径说明 PATH 里同时存在/usr/local/bin和/opt/homebrew/bin而且顺序不对。解决方法是把正确那个放到 PATH 前面或者干脆清理掉不用的那个。5.3 卸载残留与彻底重装当问题实在太多、修不如重装的时候就得先卸载干净。官方提供了一个卸载脚本思路是先把 HomeBrew 自己删掉再把各个软件删掉。因为网络原因这个脚本也可能拉不下来可以先用浏览器打开 install 仓库页面手动下载uninstall.sh到本地再执行。执行之前建议先看一眼脚本内容它会提示你有哪些目录会被删除、哪些不会。流程通常是先跑卸载脚本然后手动清理残留sudo rm -rf /opt/homebrew sudo rm -rf /usr/local/Homebrew sudo rm -rf /usr/local/Cellar sudo rm -rf /usr/local/Caskroom这里必须强调/usr/local下这几个目录要一个一个删千万不要直接rm -rf /usr/local。这个目录里有其他软件的东西整删会把别的东西一起带走我之前在论坛上见过有人这么干最后只能重装系统。删完之后还要清理 shell 配置文件里残留的 brew 相关行。打开~/.zprofile和~/.zshrc把包含brew shellenv、HOMEBREW_的行都删掉。不删的话新装的 HomeBrew 启动时会读到旧的环境变量可能指向已经不存在的路径然后你又回到command not found的起点。清理完记得开一个新终端窗口或者source ~/.zprofile让配置重新加载。6. 长期使用的维护技巧6.1 磁盘占用与定期清理HomeBrew 用久了会占掉不少空间主要来自三个方面旧版本的 Cellar 目录、下载缓存、以及不用了的依赖。我见过一台用了两年的机器~/Library/Caches/Homebrew加上旧版本文件加起来超过了 20GB。这也是很多人口中Mac 系统数据怎么清理的一个具体来源——系统设置里那块灰色的系统数据经常就有 HomeBrew 的贡献。清理命令brew cleanup -n # 先预览会删掉什么不实际执行 brew cleanup # 实际清理 brew autoremove # 删掉不再被依赖的包-n这个参数很值得养成习惯先看一眼再动手避免误删你还想留着的东西。另外brew cleanup --pruneall会把所有旧版本都删掉只保留当前版本如果你经常需要回退到旧版本就别用这个参数。6.2 Brewfile换机时的救命稻草这是我个人认为 HomeBrew 最被低估的功能。它能把当前环境里所有已安装的包导出成一个文本文件brew bundle dump --file~/Brewfile导出来的文件长这样brew wget brew jq cask google-chrome换新机器的时候只要把这个文件拷过去然后执行brew bundle install --file~/BrewfileHomeBrew 会自动把所有包重新装一遍。我换机器的时候就是靠这个把两年的环境在半小时内复原的包括各种小工具和图形应用。比一个个回忆自己装过什么靠谱多了。6.3 和开发环境的配合最后说几个实际搭配中容易出问题的点。用 HomeBrew 装 Python 之后系统自带的 Python 和 brew 装的 Python 会共存python3指向哪一个取决于 PATH 顺序。想确认的话用which -a python3看一眼。如果要在项目里用特定版本建议再装pyenv来管理别硬改 PATH。装 JDK 也是同理。brew install openjdk装完之后HomeBrew 不会自动帮你设置JAVA_HOME需要手动在~/.zprofile里加一行指向$(brew --prefix openjdk)。这一点和很多人预期的装完就能用不一样但我反而觉得这样更清晰——环境变量掌握在自己手里比被某个工具偷偷改掉要好。还有一个纯经验性的体会尽量不要用 HomeBrew 去装那些系统已经自带且你不需要新版本的东西。比如ruby、perl这类系统版本够用就别装装了之后 PATH 顺序一变可能影响到依赖系统版本的其他工具。只在确实需要更新版本或者需要某个特定依赖的时候再装能省掉很多莫名其妙的冲突。我用 HomeBrew 这几年最大的感受是它真正帮人的地方不在安装那一步而在后面几年的维护——升级、卸载、迁移、依赖管理这些琐碎事它都替你兜住了。安装过程中那些报错看着吓人拆开看无非是网络、权限、路径三类问题对照上面的表逐个排查基本都能解决。装完之后把brew cleanup和brew bundle dump这两个习惯养起来你会发现这台机器的长期状态比手动管理的时候干净得多。