NumPy2.5放弃Python3.11后CI环境怎么配?
NumPy 2.5 遵循 SPEC 0 规范正式停止支持 Python 3.11。本文深入讲解下游库和项目在 CI 流水线中的双轨配置策略、GitHub Actions 差异化矩阵编写、PEP 508 环境约束标记与常见报错排查。
Requires-Python 设为 >=3.12 并精简 CI 矩阵;若项目仍需为 Python 3.11 用户提供维护保障,则必须在 GitHub Actions 矩阵中通过 include 将 Python 3.11 节点与 numpy<2.5 显式绑定,或者在 pyproject.toml 中使用 PEP 508 环境标记进行版本隔离,杜绝在 Python 3.11 运行环境下拉取无对应 wheel 的 NumPy 2.5。
一、为什么 NumPy 2.5 会停止支持 Python 3.11?
NumPy 项目对 Python 版本的支持周期遵循科学计算生态的核心标准 SPEC 0(Scientific Python Ecosystem Coordination)。根据 SPEC 0 的生命周期规范,核心科学计算库承诺在 Python 官方发布之日起,对其提供至少 36 个月(3 年)的持续支持。
回顾 Python 版本发布历史:Python 3.11 于 2022 年 10 月正式发布,其对应的 36 个月支持窗口在 2025 年 10 月正式到期。因此,计划在此节点之后发版的 NumPy 2.5 将其构建环境与运行时环境的最低 Python 版本抬升至 Python 3.12(Requires-Python: >=3.12),并不再向 PyPI 上传针对 Python 3.11 的预编译二进制 Wheel 包。
这一调整给下游库带来的直接影响是:如果下游项目的 CI 流水线依然保留了 matrix.python-version: ['3.11', '3.12', '3.13'],且测试脚本中仅执行无版本的 pip install numpy 或 uv pip install .,包解析器便会在 Python 3.11 节点中陷入困境——要么退回到源码编译(由于缺少现代构建工具链而导致 CI 构建超时或报错崩溃),要么触发依赖冲突异常 ResolutionImpossible。
二、改造前评估:你的项目是否需要保留 Python 3.11?
在动手改动流水线配置前,团队需要先依据项目的受众和定位做出架构决策:
- 场景 A(前沿型/应用型项目):与上游同步裁撤 Python 3.11
如果你的项目是面向终端用户的数据分析脚本、Web 应用,或者只服务于内部环境,紧跟上游生态是最省力的选择。此时只需在pyproject.toml中将最低 Python 版本更新为requires-python = ">=3.12",并在 CI 矩阵中直接剔除3.11即可。 - 场景 B(开源基础库/通用依赖):维持 Python 3.11 长期支持(双轨制)
如果你的项目是发布在 PyPI 上的通用工具库,许多企业级用户或大型发行版仍运行在 Python 3.11 容器上。此时你的项目需要继续兼容 Python 3.11,但必须采用双轨制策略:在 Python 3.11 环境下测试numpy<2.5(如 2.4.x 或 2.0.x),而在 Python 3.12 及以上环境测试最新的numpy>=2.5。
三、GitHub Actions CI 矩阵具体配置实战
对于需要维持双轨兼容的项目,最稳健的做法是在 GitHub Actions 的 strategy.matrix 中使用 include 参数,将 Python 3.11 运行环境与指定的 NumPy 版本约束精确绑定。
以下是经过生产检验的标准 .github/workflows/ci.yml 配置示例:
name: CI Test Suite
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
name: Test (Py ${ matrix.python-version } | NumPy ${ matrix.numpy-spec })
runs-on: ${ matrix.os }
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest]
python-version: ['3.12', '3.13']
numpy-spec: ['latest']
include:
# 专门为 Python 3.11 设定的向下兼容测试节点
- os: ubuntu-latest
python-version: '3.11'
numpy-spec: '<2.5'
# 可选:macOS 与 Windows 重点矩阵验证
- os: macos-latest
python-version: '3.12'
numpy-spec: 'latest'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python ${ matrix.python-version }
uses: actions/setup-python@v5
with:
python-version: ${ matrix.python-version }
cache: 'pip'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
# 根据矩阵参数差异化安装 NumPy
if [ "${ matrix.numpy-spec }" = "latest" ]; then
python -m pip install "numpy>=2.5"
else
python -m pip install "numpy${ matrix.numpy-spec }"
fi
# 安装当前项目的可编辑包与测试依赖
python -m pip install -e ".[test]"
- name: Verify installed packages
run: |
python -c "import sys, numpy; print(f'Python: {sys.version} | NumPy: {numpy.__version__}')"
- name: Run Pytest
run: |
pytest tests/ -v
strategy.fail-fast: false 的设置。这能够确保即使某个版本的轮子拉取受阻,其他 Python 版本的测试结果依然完整输出,方便团队快速定位是全局性代码错误还是单版本的依赖问题。
四、包管理配置:PEP 508 动态环境标记
除了在 CI 工作流脚本中使用条件语句安装外,更彻底的做法是将这一规则沉淀在项目本身的元数据中。使用 PEP 508 环境标记(Environment Markers),能让 pip、uv 或 poetry 在任何终端自动选出合规的依赖版本。
1. 在 pyproject.toml 中声明条件依赖
[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-scientific-lib"
version = "1.2.0"
requires-python = ">=3.11"
dependencies = [
# 在 Python 3.11 下限制安装 2.5 之前的版本
"numpy>=2.0.0,<2.5.0; python_version < '3.12'",
# 在 Python 3.12 及以上优先使用 2.5+
"numpy>=2.5.0; python_version >= '3.12'",
"scipy>=1.13.0",
]
[project.optional-dependencies]
test = [
"pytest>=8.0",
"pytest-cov",
]
2. 使用 uv 管理通用锁文件(Universal Lockfile)
如果你的 CI 流水线采用现代包管理工具 uv 进行极速安装,推荐使用通用锁机制(Universal Resolver)。在仓库根目录执行生成跨平台锁文件:
# 生成同时适配 3.11 与 3.12+ 的自洽锁文件
uv lock
# 在 CI 流水线中直接根据当前环境无损同步
uv sync --locked --extra test
uv 的解析器会严格评估 python_version < '3.12' 标记,在 Python 3.11 节点上解析出 numpy-2.4.x,而在高版本节点上安装 numpy-2.5.x,无需手动书写 shell 分支判断逻辑。
五、避坑指南与常见报错排查
在迁移或调试 CI 环境时,开发者常遇到以下三类典型问题,可按以下指引排查:
| 报错表现 | 根本原因 | 排查与解决方案 |
|---|---|---|
ERROR: Could not find a version that satisfies the requirement numpy>=2.5.0 |
在 Python 3.11 的 Runner 上强行执行了 pip install numpy>=2.5.0,因缺少对应 Wheel 且源码声明了更高版本的 Python。 |
检查 CI 矩阵参数,确保在 matrix.python-version == '3.11' 时指定了 numpy<2.5。 |
RuntimeError: module compiled against API version 0x... but this version of numpy is 0x... |
C/Cython 扩展在构建时使用了旧版 NumPy 头文件,运行时却加载了新版(或反之)。 | 遵循 NumPy 2.0+ 构建规范:在 build-system.requires 中使用 numpy>=2.0.0 编译,此二进制向前兼容所有 2.x 运行时。 |
| CI 依赖安装命中意外旧包,更改配置后依然复现。 | GitHub Actions 的 pip 缓存键未包含 Python 版本维度,导致 Python 3.12 误复用了 3.11 的缓存包。 | 优化 Cache Key,确保包含 ${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}。 |
六、总结与落地清单
NumPy 2.5 放弃 Python 3.11 是科学计算生态遵循 SPEC 0 规范的正常技术演化。处理好此次 CI 环境升级的关键可以概括为三个动作:
- 明确边界:在项目元数据中准确界定
requires-python,确定是否需要继续向下兼容 Python 3.11。 - 双轨解耦:通过 GitHub Actions 差异化矩阵与 PEP 508 环境标记,将旧版本 Python 与受限的 NumPy 版本绑定,高版本直接接入最新生态。
- 验证隔离:确保 CI 缓存颗粒度精确到单个 Python 小版本,并在构建日志中打印运行时确切的 NumPy 版本,确保预期配置真实生效。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













