前两天在 Mac M2 上准备用 brew 装一个开发依赖敲下brew install之后屏幕没有像往常一样刷出安装进度而是直接甩出一行红字unknown or unsupported macOS version: 26.3 (MacOSVersionError)。紧接着我试了brew --version、brew update结果全部一样都是同一个错误。那一刻有点懵——brew 不是刚还好好的吗后来排查了一圈才明白这不是网络问题也不是依赖冲突而是 brew 包管理器在执行任何命令之前都会先做一次系统版本自检它内部维护着一个“已知可用的 macOS 版本列表”列表里没有你想不到的大版本号它就认为当前系统不受支持直接罢工。换句话说你并不是做了什么违规操作而是系统版本号跨过了 brew 内置列表的上限触发了一个保护机制。这篇文章就围绕这个报错完整记录一次排查过程。如果你也遇到了同样的MacOSVersionError或者单纯想搞清楚 brew 在跑之前到底检查了什么这篇内容应该能帮你省下不少时间。我会按“先理解机制、再动手排查、最后修复与预防”的顺序来写尽量把每一步的原理和操作都讲透。1. MacOSVersionError 不是网络问题是 brew 的版本白名单机制罢工了1.1 brew 每次执行命令前到底做了什么很多人以为 brew 是个普通命令行工具敲什么就执行什么。其实不是。brew 的背后是一个 Git 仓库它每次运行命令时会先加载一堆 Ruby 脚本其中有一个步骤就是读取当前 macOS 的版本号然后和内部维护的版本列表做对比。这个版本列表可以理解成一张白名单里面记录了“brew 官方已知并支持的 macOS 大版本号”比如 11、12、13、14、15、26 这样的大版本。检测逻辑大致是这样的先通过系统接口拿到当前版本号比如26.3再用版本解析逻辑拆出主版本号也就是26最后拿这个主版本号去白名单里找。如果找不到就会抛出一个MacOSVersionError错误信息里会带上你本机的完整版本号比如标题里的26.3。这里的关键点是brew 的所有子命令都经过这个前置检查所以一旦版本校验失败不只是brew install不能用brew update、brew doctor、甚至brew --version都会一起瘫痪。这也是为什么很多人在网上搜到“执行 brew update 试试”的答案后发现根本执行不了——因为 update 也得先过版本检查这道关卡。1.2 “26.3” 这个版本号是怎么触发判定的涨知识之前先明确一点报错信息里出现的26.3本身是当前 macOS 系统报告给 brew 的版本号。你的系统已经进入了26.x这个大版本时代而 brew 内置白名单的更新速度没跟上或者你本地的 brew 仓库长时间没有拉取过最新代码导致它并不认识这个版本号。这里有两个变量需要区分清楚第一个是brew 本身版本落后你安装的 brew 可能是几个月前甚至一年前装的期间一直没有更新。brew 的上游仓库早就加入了对新版本号的支持但你本地的代码还是旧的所以白名单里自然缺失。第二个是brew 官方还没来得及支持系统新版本刚发不久brew 官方的版本定义文件还没有合入新的版本号。这种情况下即使你把 brew 更新到最新本地代码也可能依旧不认识这个版本号。我遇到的情况属于前者。排查的时候用系统自带命令看了一眼 macOS 版本确实是26.3然后去 brew 仓库里翻版本定义文件发现白名单列表确实没有26。这种问题最典型的特征就是系统版本比 brew 的“认知”更超前。顺带说一句MacOSVersionError在 M2 这类 Apple Silicon 芯片上尤其容易遇到。因为很多人的 brew 是买了新机器之后一次性装的装完就再也没主动更新过。系统倒是勤快地升级了好几轮等某个大版本号一跨过白名单边界报错就爆出来了。2. 动手修复前先花 5 分钟把机器状态摸清楚2.1 确认三样东西系统版本、芯片架构、brew 安装路径我见过不少人一看到报错就急着重装 brew结果装完发现问题还在或者更惨直接把已经安装的软件包全部弄丢了。所以在做任何修复动作之前先花几分钟确认三个基本信息能帮你少走很多弯路。第一是确认系统版本号。最直接的方法是运行sw_vers输出结果里会有一行ProductVersion比如26.3。记住这个数字后面手动改 brew 的版本列表时要用到它的大版本号。ProductVersion: 26.3ProductName: macOSProductVersionExtra: (null)第二是确认芯片架构。在 M2 这类机器上运行uname -m如果输出是arm64说明你正在使用 Apple Silicon 原生终端。如果输出是x86_64那你可能是在 Rosetta 模拟环境下运行的终端这会直接影响 brew 的安装路径和后续修复方式。第三是确认 brew 的安装路径。运行command -v brew或者which brew在 Apple Silicon 机器上正常情况下输出会是/opt/homebrew/bin/brew而在 Intel 芯片的 Mac 上路径通常是/usr/local/bin/brew。这两个路径对应的 brew 仓库位置不同后面修改文件时必须对号入座不能搞混。2.2 用 git 直接查看 brew 仓库的落后程度brew 的原理决定了它本质上是一个 Git 仓库。你完全可以用 Git 命令直接查看这个仓库的状态而且这些 Git 操作不受MacOSVersionError的影响——因为它们根本不经过 brew 的版本自检逻辑。如果 brew 在/opt/homebrew那么仓库根目录就是/opt/homebrew。我一般会这样检查cd /opt/homebrew git status正常情况下输出会提示你在哪个分支、以及是否领先或落后于远程仓库。然后看最近几次提交git log --oneline -10如果这个仓库的最近提交时间还停留在几个月前那基本可以断定问题出在本地代码过旧。再对比一下远程仓库的位置git remote -v这一步的意义在于确认 brew 仓库的远程地址是否指向官方源。如果远程地址没问题就可以放心地进行下一步强制拉取。万一远程地址被改过那就要先处理好远程源再谈更新问题。2.3 不同的环境分支决定后续修复路径把信息摸清楚之后问题基本可以归入以下几类分支A本地仓库版本落后且能连通远程仓库。这种情况最简单直接用 Git 拉取最新代码就能让白名单包含26这个版本号。分支B本地仓库损坏或者 Git 操作报错。比如.git目录有问题、文件权限被改乱这种情况下需要先修复仓库状态再考虑更新。分支C本地代码已经是最新但白名单里依然没有26。这说明 brew 官方还没支持这个版本号你需要手动往版本定义文件里补上缺失的数字。分支D终端环境无小事。比如你在 Rosetta 模拟环境下操作或者 homebrew 的目录权限不对都可能导致你改的文件没生效。后面第三节的修复路线基本就是按照这几种分支来设计的先用最小干预的手段解决不了再升级为手动改文件一步步提高操作的“侵入性”。3. 一条稳妥的修复路线从最小干预到手动改文件3.1 先试 git 强制拉取让版本列表同步到最新排查完环境之后我最先采用的是重置 brew 仓库到最新版。因为 brew 的更新机制本来就是“拉代码”既然报错发生在命令入口那我们就绕过入口从仓库层面直接操作。在 Apple Silicon 机器上cd /opt/homebrew git fetch origin git reset --hard origin/master git pull第一条命令从远程拉取最新的提交历史第二条命令把本地仓库强制重置到远程分支的状态第三条命令确保你所在的分支确实在最新提交上。执行完之后brew 的版本定义文件就会包含上游仓库里最新的白名单数据。为什么不用brew update因为brew update也要先过版本自检而当前环境根本过不去。用原始 Git 命令的好处是绕开了这层检查直接从仓库层级解决问题。这也是很多网上的教程没有讲清楚的一点——报错期间你需要用 Git 而不是 brew 来更新 brew。执行完git pull之后再验证一次brew --version如果正常输出了版本号说明修复成功。我记得我第一次刷出版本号的时候心里还挺踏实的至少不用折腾重装。3.2 拉不动的时候用临时变量先让 brew 恢复工作有时候 Git 拉取也会遇到问题比如网络受限、远程仓库 timeout、或者本地仓库状态乱到 reset 都拉不回来。这时候你依然可以临时“骗过”版本自检先把 brew 救活再决定要不要继续升级。方法之一是用 Homebrew 支持的环境变量。在 bash/zsh 下这样写export HOMEBREW_DEVELOPER1这个变量会让 brew 进入开发者模式。在很多场景下开发者模式会放宽对系统版本校验的限制。设完环境变量后再试brew --version如果还是报同样的错误可以再尝试指定 brew 认为当前系统应该使用的主版本号export HOMEBREW_MACOS_VERSION26注意这只是临时绕过不等于系统真的变成了 26。它只是告诉 brew“把当前版本当作 26 来处理”从而让装有新旧依赖的 Formula 公式能继续走流程。过了这关之后brew install有可能恢复正常但我不建议长期依赖这个状态因为一旦系统版本和 brew 的代码逻辑不完全匹配后续安装某些依赖时可能还会踩到别的坑。用临时变量绕过版本检查的另外一个风险在于你可能会忘记自己设过环境变量。下次重启终端后环境变量会消失到时候问题会再次出现。所以这个方法只能作为“过渡手段”最终还是要落实到更新或者手动补版本号上。3.3 最后手段手动把缺失的版本号补进 brew 的检查文件如果 Git 拉取不顺利、临时变量也不管用那就只能打开 brew 的版本定义文件手动把26补进白名单里。这个方法最直接也最容易理解。先找到 brew 仓库目录。Apple Silicon 上一般是/opt/homebrewIntel 上一般是/usr/local。进入目录后版本检查逻辑相关的文件通常位于cd /opt/homebrew/Library/Homebrew/os/mac ls你能看到一个类似version.rb的文件。在较新的 brew 版本里这个文件里会有一段版本判断逻辑维护着一个已知 macOS 版本集合。用文本编辑器打开它nano /opt/homebrew/Library/Homebrew/os/mac/version.rb找到包含版本号列表的那段代码。它可能是类似这样的一段判定逻辑里面列出了一堆数字... when 15, 26 ...你要做的事情很明确找到这段版本列表看里面有没有26。如果没有就把它加进去。有的版本里列表可能以数组形式存在直接在数组里加一个数字即可。保存退出后运行brew --version这是最“硬核”的修复方式相当于手动给 brew 开了个后门让它认你这个版本号。补充一句修改 brew 内部文件确实是下策因为你改了之后下一次 brew 自更新可能会覆盖掉你手动加的内容也可能因为版本判断逻辑变化而出现未知行为。但它是在紧急情况下最有效的“救火手段”很多人实际操作下来也觉得比重装省心很多。3.4 完整排查链路复盘一次从报错到修复的真实过程把整个过程串起来看你可以把它当作一份可复盘的排查链路。我的实际操作顺序大概是这样的第一步复现问题。先运行brew install记录报错原文确认错误类型是MacOSVersionError。第二步采集基础信息。运行sw_vers、uname -m、which brew把系统版本、芯片架构、brew 路径记下来。第三步尝试更新。发现brew update无法执行因为同样被版本自检拦截。第四步用 Git 查看仓库状态确认本地代码落后远程源正常。第五步执行git reset --hard origin/master强制同步。第六步验证恢复运行brew --version确认输出正常。第七步回归业务重新执行原先失败的那条brew install。这条链路里最容易被卡住的是第四步到第五步之间。很多人会在“无法执行 brew update” 这一步上面循环尝试但其实只要思路转一下从 brew 的命令层切到 Git 的仓库层问题就能顺畅解开。这里的经验是当工具本身的自检逻辑挡住了工具的更新通道时第一步不是修工具而是想想这个工具底层还有什么通道没有被挡住。4. 这次修复里最容易踩的四个坑4.1 改错文件位置Apple Silicon 和 Intel 的目录完全不同这个坑最典型也最容易犯。网上搜MacOSVersionError时很多教程写的是/usr/local/Homebrew/Library/Homebrew/os/mac/version.rb。结果在 M2 机器上按照这个路径去找发现目录根本不存在。原因在于Apple Silicon 的 brew 默认安装在/opt/homebrew而 Intel 的 brew 安装在/usr/local。这两个路径的系统目录结构完全不同。你如果用 Intel 的路径改 M2 的 brew改半天也没反应因为改的文件根本不在 brew 实际加载的位置。所以操作之前一定要先确认command -v brew的路径。路径的输出直接决定了后面所有操作应该在哪层目录里进行。这件事很容易被忽略但恰恰是“改完没生效”的头号原因。4.2 忽略权限问题导致修改无效第二个坑和权限有关。/opt/homebrew目录下有些文件的所有者可能是 root当前用户只有读权限。如果你直接编辑这些文件编辑器保存时会提示“Permission denied”。这时候千万别想着用 sudo 强行改文件因为改了之后文件所有者就变了brew 运行时可能出现更奇怪的权限错误。正确做法是先把目录归属权修好sudo chown -R $(whoami) /opt/homebrew然后重新编辑version.rb。这一步的本质是让 brew 仓库回到“当前用户完全拥有”的状态这也是 brew 正常运行的基本前提。修好权限后再改版本号成功率会高很多。4.3 以为 brew update 是万能药当MacOSVersionError出现时很多人第一反应就是“那我先 update 一下”。问题是brew update本身就是 brew 命令它一样会被前置版本自检拦住。换句话说走 brew 自己的通道在报错状态下根本走不动。真正能走通的通道有两个一是用 Git 命令直接操作仓库二是临时用环境变量跳过自检。别浪费时间反复尝试brew update除非你已经通过其他手段把 brew 的命令层恢复过来否则它会一直躺在原地报一样的错。4.4 临时绕过后的残留影响用HOMEBREW_DEVELOPER1或者HOMEBREW_MACOS_VERSION26绕过版本检查之后如果问题解决了很多人就不再管环境变量了。但别忘了一个细节环境变量只在当前终端会话有效。你关掉终端再开或者重开一个窗口env 就没了。到时候再跑 brew报错可能再次出现。更值得担心的是某些临时变量会影响 brew 的依赖解析逻辑。用开发者模式绕过时brew 可能会跳过一些它对系统库的兼容性判断导致你装的包在运行时因为系统库版本不一致而出问题。所以我的建议是临时变量只用来“救急”救完急之后一定要回到正式的更新路径上把 brew 恢复成“不带任何环境变量也能正常工作”的状态。5. 修复之后怎么让 brew 不再因为系统升级而瘫痪5.1 把系统大版本升级变成固定流程遇到过一次MacOSVersionError后我把“系统升级”和“brew 更新”这两件事彻底捆绑在了一起。具体来说每次 macOS 大版本升级之前我会先手动执行一次brew update如果担心依赖更新带来不兼容就先跑brew outdated看看有哪些包需要升级再决定升级顺序。这样系统升到新版本时brew 已经在运行新版代码它的白名单里大概率已经包含新版本号自检就能顺利通过。这个习惯看起来简单但它能帮你避开大量“系统升完级开发工具集体罢工”的场景。很多报错根本不是 brew 官方不支持新系统而是你本地 brew 太久没更新导致它的认知还停留在旧系统时代。5.2 定期体检brew doctor 的正确使用姿势brew doctor是一个很容易被忽略的命令但它在解决这类问题上的价值很高。修复完MacOSVersionError之后我会习惯性跑一次brew doctor它会把 brew 当前存在的问题列出来比如目录权限不对、符号链接失效、环境变量冲突等。细看输出信息很多问题你平时根本察觉不到但积累到一定程度就会以各种奇怪报错的形式爆发。有一点需要注意的是brew doctor的输出会包含很多警告有些警告对特定人群可以忽略比如环境变量里的自定义链接目录。不要一上来就想着把所有警告都清零而是挑选跟系统版本、文件路径、权限相关的警告来处理。这比我以前“看到 warning 就害怕一股脑全按教程修复”的效率高很多。5.3 掌握 brew bundle让极端情况下也能快速恢复修好这次报错后我顺手做了一件很值得推荐的事用 brew bundle 导出当前已安装的所有软件清单。brew bundle dump --file~/BrewfileBrewfile 里会记录当前 brew 安装的所有 Formula 和 Cask。之后哪怕 brew 仓库彻底损坏、需要重装也可以在新环境下快速恢复brew bundle install --file~/Brewfile这对于靠 brew 维护整套开发依赖的人来说算是一份“保险”。我在经历过这次MacOSVersionError之后才意识到平时多花一分钟做一次 dump关键时刻能帮你省掉几个小时的重装时间。它不会直接防止报错但只要报错极端到必须重装你就有了一键复原的底牌。说到底unknown or unsupported macOS version: 26.3这类报错的本质是版本更新节奏不匹配。系统在往前走brew 的认知库没能及时跟上。修复手段其实都很简单难的是快速判断出“该走哪条通道”。以我个人的经验最值得记住的一点就是brew 本身是 Git 仓库命令入口坏了就从仓库入口修。下次如果你也撞上 MacOSVersionError别急着重装先看一眼 brew 的安装路径再试试用 Git 强制同步一次多半就能解决。修复完之后记得跑一遍 brew doctor再补一份 Brewfile这套流程走下来类似的问题基本就和你没什么缘分了。