macOS 26 上一个诡异的 Python Bug,我排查了整整一个晚上

事情是这样的。

最近在 GitHub 上刷到一个项目叫 code-review-graph，能把代码 review 的过程画成知识图谱。我对这种 AI 开发工具链没什么抵抗力，第一反应就是装上试试。

官方文档说安装就一行命令：

pipx install code-review-graph

我敲下去，回车，等它跑完。

结果直接糊了一脸报错：

error: Failed to inspect Python interpreter from provided path at/opt/homebrew/opt/python@3.14/libexec/bin/pythonCaused by: Can't use Python at /opt/homebrew/opt/python@3.14/libexec/bin/pythonCaused by: Broken Python installation,platform.mac_ver() returned an empty value

我愣了一下。

Broken Python installation？Python 装坏了？

前两天还好好的，我也没动过什么。第一反应是 Homebrew 又抽风了，但再看报错，指向的是一个很具体的函数 platform.mac_ver()，不是那种“你的 Python 炸了”的模糊提示。

有意思。决定追下去。

第一步，验证 Python 是不是真的坏了

报错说 platform.mac_ver() 返回空值，那就直接测：

/opt/homebrew/opt/python@3.14/libexec/bin/python -c "import platformprint(platform.mac_ver())"

输出：

('', ('', '', ''), '')

确实是空的。

正常应该是这样：

('26.2', ('', '', ''), 'arm64')

至少这个函数确实出问题了。但光一个函数异常，不代表整个 Python 都坏了。

第二步，确认系统本身有没有问题

先看系统版本：

sw_vers

输出：

ProductName:    macOSProductVersion: 26.2BuildVersion:   25C56

是 macOS 26.2，Tahoe。

再确认：

sw_vers -productVersion

26.2

系统版本号正常，macOS 本身没问题。

第三步，测一下 Python 的其它能力

同一个 Python 继续检查：

python3.14 -c "import platformimport osprint(platform.platform())print(platform.uname())print(os.uname())"

输出：

Darwin-25.2.0-arm64-arm-64bit-Mach-Ouname_result(...)posix.uname_result(...)

uname 正常，架构识别正常，Darwin 内核版本也正常。

也就是说，Python 并不是“坏了”，只是 platform.mac_ver() 这一个函数出了问题。

第四步，怀疑是 Python 3.14 跟 macOS 26 的兼容性问题

Python 3.14 是预发布版本，macOS 26 也是新系统。两个新东西凑一块，出兼容性问题太正常了。

于是我装了一个 Python 3.13：

brew install python@3.13

然后测试：

/opt/homebrew/bin/python3.13 -c "import platformprint(platform.mac_ver())"

结果：

('', ('', '', ''), '')

一样。

排除了“Python 3.14 独有的 bug”。问题出在别的地方。

第五步，关键发现

我机器上还有一套 Claude Code 自带的 Python，在 ~/.claude/.venv/ 下面。这套 Python 是我用 uv 装的，uv 下载的是官方 CPython 二进制，跟 Homebrew 自己编译的不是一回事。

抱着试试看的心态跑了一下：

/Users/xxx/.claude/.venv/bin/python3 -c "import platformprint(platform.mac_ver())"

输出：

('26.2', ('', '', ''), 'arm64')

完全正常。

这下范围小了。macOS 26.2 没问题，platform.mac_ver() 也没问题，出问题的是 Homebrew 构建出来的 Python。

同样的代码，同一个操作系统，uv 下载的官方 CPython 能正常返回版本号，Homebrew 自己编译的 Python 返回空值。

原因大概是这样：uv 下载的官方 CPython 是用较新 SDK 编译的，读取 SystemVersion.plist 时不会被 Apple 的版本号兼容机制误导。而 Homebrew 在本地编译 Python 时，用的 SDK 版本跟 macOS 26 之间可能存在不匹配，导致 mac_ver() 解析失败，直接抛空。

第六步，才发现机器上已经乱成一锅粥

继续排查时跑了一个最朴素的命令：

which python3

输出：

/usr/bin/python3

居然是系统自带的 Python 3.9.6。

查了一圈，这台机器上至少有四套 Python：

• • /usr/bin/python3，系统自带，Python 3.9
• • /opt/homebrew/bin/python3.13，Homebrew 装的
• • ~/.claude/.venv/bin/python3，Claude Code 虚拟环境，使用 uv 安装
• • ~/.local/bin/python3.13，uv 管理的独立 Python

典型的 Python 环境地狱。

你以为自己在用 A Python，实际上工具链里的某个环节调的是 B Python。pipx 底层用 uv 创建虚拟环境，uv 在检测 Python 解释器时选了 Homebrew 那个有问题的 Python，然后 platform.mac_ver() 返回空值，uv 就直接判定“这个 Python 装坏了”。

链条是这样的：

pipx  → uv venv    → 选了 Homebrew Python      → platform.mac_ver() 返回空        → uv 判定 Broken Python          → 安装失败

每一步看起来都合理，但组合在一起就是个诡异的报错。

根因到底是什么

追到根上，这是 Apple 的一个“兼容性设计”。

macOS 的版本号从 15.x 直接跳到了 26.x，Apple 改用了年份版本号。但很多老程序检查版本号时写的是“如果主版本号大于 15 就怎样怎样”，这种假设在新系统上会炸。

Apple 的解决方案很粗暴：对不同 SDK 编译的程序，系统返回不同的版本号。

用 SDK 26 编译的程序去读 SystemVersion.plist，返回 26.0。用旧版 SDK 编译的程序去读同一个文件，系统会在背后偷偷换成 16.0。

这不是 bug，是 Apple 的 feature。