迁移至NumPy 2遇阻：numpy.core.multiarray导入失败求助

结合你遇到的问题（仅cibuildwheel构建的Release流水线报错，直接安装源码的Test流水线正常），核心原因大概率是构建轮子时的NumPy环境与测试环境不匹配，或是numpy.import_array()的调用时机/位置有误，以下是具体排查和解决步骤：

1. 对齐构建与测试环境的NumPy版本 #

cibuildwheel在隔离环境中构建轮子，若构建时使用的NumPy版本和测试时安装的NumPy 2.x版本ABI不兼容，就会触发导入错误。

• 在pyproject.toml中明确指定构建依赖的NumPy版本为2.x：

  [build-system]
  requires = ["setuptools", "wheel", "cython", "numpy>=2.0"]
  build-backend = "setuptools.build_meta"
  

• 在Release流水线的安装步骤中，强制安装对应版本的NumPy：

  python -m pip install --force-reinstall --find-links dist openTSNE numpy>=2.0
  

2. 修正numpy.import_array()的调用位置 #

.pxd文件是声明文件，不需要添加初始化代码，只需在**每个.pyx模块的顶层（cimport numpy之后，任何C级数组操作之前）**调用一次即可，无需在每个cpdef函数中重复调用：

cimport numpy as cnp

# 模块初始化时调用，仅需一次
cnp.import_array()

# 后续的函数定义、数组操作等
cpdef void some_function(cnp.ndarray[double, ndim=2] arr):
    # ...

3. 检查cibuildwheel的构建配置 #

确保cibuildwheel在构建时使用正确的Python和NumPy环境：

• 在项目根目录添加cibuildwheel.toml，指定构建时的依赖：

  [tool.cibuildwheel]
  before-build = "pip install cython numpy>=2.0"
  

• 彻底移除oldest-supported-numpy相关配置，确保构建环境直接使用NumPy 2.x。

4. 验证轮子的兼容性 #

在Release流水线中添加轮子检查步骤，确认依赖是否正确：

# 安装auditwheel
pip install auditwheel
# 检查轮子的依赖和ABI兼容性
auditwheel show dist/*.whl

输出中应显示轮子依赖的NumPy版本与测试环境一致，且无ABI不兼容的警告。

5. 排查模块导入顺序 #

若项目包含多个Cython模块，确保第一个被导入的模块已经执行了cnp.import_array()。NumPy的数组初始化只需执行一次，若某个模块在初始化时先触发了NumPy数组操作但未调用初始化函数，就会报错。可在项目的__init__.py中显式导入初始化过的模块，确保初始化顺序正确。

内容的提问来源于stack exchange，提问作者Pavlin