NumPy2.5放弃Python3.11后CI环境怎么配?

Evan
Evan
发布时间:2026-11-18 | 7人浏览过
原创

NumPy 2.5 遵循 SPEC 0 规范正式停止支持 Python 3.11。本文深入讲解下游库和项目在 CI 流水线中的双轨配置策略、GitHub Actions 差异化矩阵编写、PEP 508 环境约束标记与常见报错排查。

CI / CD 工程化实践
适用场景:Python 科学计算生态、下游依赖库迁移、GitHub Actions 流水线维护
核心结论与快速行动路径:当 NumPy 2.5 停止支持 Python 3.11 并移除对应预编译轮子后,CI 流水线修复的核心逻辑在于“依赖分流”。若你的项目与 NumPy 同步放弃 Python 3.11,只需将 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。
NumPy2.5放弃Python3.11后CI环境怎么配?
图 0:NumPy 2.5 弃用 Python 3.11 后的 CI 兼容矩阵演进概览

一、为什么 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 包。

NumPy2.5放弃Python3.11后CI环境怎么配?
图 1:SPEC 0 规范下各 Python 版本支持窗口与 NumPy 对应演进关系

这一调整给下游库带来的直接影响是:如果下游项目的 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。
NumPy2.5放弃Python3.11后CI环境怎么配?
图 2:双轨制 CI 矩阵测试架构与依赖流向设计

三、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 版本的测试结果依然完整输出,方便团队快速定位是全局性代码错误还是单版本的依赖问题。
NumPy2.5放弃Python3.11后CI环境怎么配?
图 3:CI 环境配置改造四步标准操作流程

四、包管理配置: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') }}。
NumPy2.5放弃Python3.11后CI环境怎么配?
图 4:CI 治理清单与配置速查决策树

六、总结与落地清单

NumPy 2.5 放弃 Python 3.11 是科学计算生态遵循 SPEC 0 规范的正常技术演化。处理好此次 CI 环境升级的关键可以概括为三个动作:

  1. 明确边界:在项目元数据中准确界定 requires-python,确定是否需要继续向下兼容 Python 3.11。
  2. 双轨解耦:通过 GitHub Actions 差异化矩阵与 PEP 508 环境标记,将旧版本 Python 与受限的 NumPy 版本绑定,高版本直接接入最新生态。
  3. 验证隔离:确保 CI 缓存颗粒度精确到单个 Python 小版本,并在构建日志中打印运行时确切的 NumPy 版本,确保预期配置真实生效。
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表