📚 课程目录第4章版本约束与兼容性语义

4. 版本约束与兼容性语义

在科学计算环境中，“装哪个版本”往往比“装什么包”更容易引发事故。一个看似无害的 pip install numpy 可能把整个环境从可复现状态推向崩溃，原因在于版本号背后承载着三层不同的语义：语义化版本表达作者对变更性质的承诺，版本范围表达依赖解析器可接受的解空间，锁定文件则把解空间收敛为一个确定点。理解这三层语义，是判断“升级是否安全”的基础。

语义化版本：承诺而非事实

语义化版本（SemVer）约定 MAJOR.MINOR.PATCH：主版本号变更表示不兼容的 API 修改，次版本号表示向后兼容的功能新增，修订号表示向后兼容的问题修复。科学计算库大多遵循这一约定，但存在两个现实偏差需要警惕。其一，0.x 版本被视为开发期，任何次版本号提升都可能破坏兼容性，例如 scipy 0.19 → 0.20 曾移除若干旧接口。其二，语义化版本只约束 API，不约束 ABI。NumPy 的 C-API 在次版本间通常保持源码兼容，但编译出的二进制扩展仍可能因内部结构体布局变化而失效。

因此，读版本号时要区分“作者承诺”与“实际行为”。对于 numpy 1.24 → 1.25，SemVer 承诺 API 兼容，但若某个第三方包是针对 1.24 的 C-API 编译的 wheel，升级后仍可能报 undefined symbol 或段错误。这正是科学计算环境比纯 Python 项目更脆弱的原因。

版本范围：解空间的表达

依赖声明中的版本范围决定了解析器可以挑选哪些版本。常见写法包括：

numpy>=1.21,<2.0：区间约束，最常用，明确排除 2.0 的不兼容变更。
numpy~=1.24.0：兼容释放，等价于 >=1.24.0,<1.25.0，只允许修订号变化。
numpy==1.24.3：精确锁定，用于复现，但会阻碍安全补丁。
numpy!=1.24.1：排除已知问题版本。

范围越宽，解析器越容易找到可行解，但结果越不确定；范围越窄，复现性越强，却越容易与其他包的约束冲突。实践中推荐“库用宽范围、应用用锁定”：被依赖的库声明 >=x,<y 给下游留空间，而最终应用通过锁定文件固定全部传递依赖的精确版本。

锁定文件：把解空间收敛为确定点

锁定文件记录的是“某次成功解析的完整结果”，包括直接依赖与传递依赖的精确版本、哈希值甚至 wheel 来源。以 pip-tools 为例，requirements.in 写范围，pip-compile 生成 requirements.txt：

# requirements.in
numpy>=1.24,<2.0
scipy>=1.10
pandas>=2.0

# 生成的 requirements.txt（节选）
numpy==1.24.4
    # via pandas, scipy
scipy==1.11.4
    # via -r requirements.in
pandas==2.1.4
    # via -r requirements.in

锁定文件的价值在于把“范围”变成“点”，使不同机器、不同时间安装出完全一致的依赖图。但它也有代价：锁定文件不会自动获得安全更新，需要定期重新编译并测试。对于科学计算，还应锁定 Python 解释器版本与 BLAS 后端，因为同一 NumPy 版本链接 OpenBLAS 或 MKL 时，数值结果与性能都可能不同。

ABI 与 API 兼容性：科学计算库的特殊规则

API 兼容指源码层面函数签名、参数、返回值不变；ABI 兼容指已编译的二进制扩展无需重新编译即可加载。科学计算库的兼容性判断应遵循以下规则：

Python 次版本不保证 ABI 兼容：为 CPython 3.10 编译的扩展不能在 3.11 中加载，因此 wheel 文件名带 cp310 标签，环境迁移时必须匹配解释器版本。
NumPy C-API 有版本门槛：扩展在编译时声明目标 API 版本，运行时若 NumPy 低于该版本会报错。升级 NumPy 主版本（如 1.x → 2.x）通常要求所有依赖 C-API 的包重新编译。
优先使用 wheel 而非源码编译：官方 wheel 已针对特定 NumPy ABI 构建，混用源码编译包容易引入 ABI 不一致。
检查 pip check 与导入测试：安装后运行 python -c "import numpy, scipy, pandas" 并执行一次小规模数值计算，比只看版本号更能发现 ABI 问题。

不要用“版本号看起来兼容”替代实际导入验证。ABI 问题往往在导入或首次调用 C 函数时才暴露，且可能表现为段错误而非友好异常。

一个可执行的判断示例

假设某项目声明 numpy>=1.24,<2.0，并依赖一个仅提供 cp310 wheel 的第三方扩展。迁移到 Python 3.11 环境时，解析器可能仍能选出 numpy==1.24.4，但该扩展没有 3.11 的 wheel，只能源码编译；若其源码针对旧 C-API 编写，编译或导入阶段就会失败。此时正确的处理顺序是：先确认解释器与 wheel 标签匹配，再确认扩展声明的 NumPy API 版本，最后才考虑放宽 NumPy 范围。盲目把 numpy 升到 2.x 往往会让问题更复杂。

迁移前先导出当前环境的精确清单：pip freeze > env-lock.txt，并记录 python --version 与 numpy.__version__。这份快照是判断“新环境差异在哪里”的基准。

总结来看，版本约束不是简单的字符串匹配，而是一条从“作者承诺”到“解空间”再到“确定点”的语义链，最终必须落到解释器版本、C-API 门槛与实际导入验证上。只有把 SemVer、范围语法、锁定文件和 ABI 规则放在同一条判断链中，才能在科学计算环境迁移时做出可解释、可复现的决策。