前两天在 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_DEVELOPER=1这个变量会让 brew 进入开发者模式。在很多场景下，开发者模式会放宽对系统版本校验的限制。设完环境变量后再试：
brew --version如果还是报同样的错误，可以再尝试指定 brew 认为当前系统应该使用的主版本号：
export HOMEBREW_MACOS_VERSION=26注意，这只是临时绕过，不等于系统真的变成了 26。它只是告诉 brew“把当前版本当作 26 来处理”，从而让装有新旧依赖的 Formula 公式能继续走流程。过了这关之后，brew install有可能恢复正常，但我不建议长期依赖这个状态，因为一旦系统版本和 brew 的代码逻辑不完全匹配，后续安装某些依赖时可能还会踩到别的坑。
用临时变量绕过版本检查的另外一个风险在于：你可能会忘记自己设过环境变量。下次重启终端后环境变量会消失，到时候问题会再次出现。所以这个方法只能作为“过渡手段”，最终还是要落实到更新或者手动补版本号上。
3.3 最后手段：手动把缺失的版本号补进 brew 的检查文件
如果 Git 拉取不顺利、临时变量也不管用，那就只能打开 brew 的版本定义文件，手动把26补进白名单里。这个方法最直接，也最容易理解。
先找到 brew 仓库目录。Apple Silicon 上一般是/opt/homebrew，Intel 上一般是/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_DEVELOPER=1或者HOMEBREW_MACOS_VERSION=26绕过版本检查之后，如果问题解决了，很多人就不再管环境变量了。但别忘了一个细节：环境变量只在当前终端会话有效。你关掉终端再开，或者重开一个窗口，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，这套流程走下来，类似的问题基本就和你没什么缘分了。
