cibuildwheel构建Python C扩展如何引入numpy arrayobject.h头路径

踩坑的核心原因是tool.cibuildwheel.environment配置块的变量解析时机早于所有构建流程：包括构建隔离环境创建、build-system.requires依赖安装、before-build步骤执行，这个阶段构建环境里还没有安装numpy，任何调用numpy获取路径的命令都会直接失败，哪怕把CFLAGS写在这个块里也会遇到完全一样的问题。另外手动拼接的/core/include/numpy路径没有版本兼容性保证，不同numpy版本的目录结构存在差异，不要自行拼接路径。

完全不需要手动设置C_INCLUDE_PATH或者手动查找头文件路径，numpy官方提供了标准的构建集成接口，所有主流Python C扩展构建后端都原生支持，自动适配Linux/Windows/macOS全平台，从根本上规避时机问题：

• 首先在pyproject.toml的构建依赖里声明numpy：

[build-system]
requires = ["setuptools>=64", "wheel", "numpy>=1.20"] # 版本下限根据实际兼容需求调整
build-backend = "setuptools.build_meta"

• 如果用setuptools作为构建后端，直接在setup.py中调用numpy官方提供的numpy.get_include()接口，把返回的路径传给扩展配置的include_dirs参数即可，这个逻辑会在构建环境完全就绪、numpy安装完成后才执行：

from setuptools import setup, Extension
import numpy as np

your_ext = Extension(
    name="your_package.your_ext_module",
    sources=["src/your_ext.c"],
    include_dirs=[np.get_include()] # 自动返回当前环境下numpy头文件的标准路径，无需手动拼接
)

setup(ext_modules=[your_ext])

• 如果用meson-python作为构建后端，直接在meson构建脚本中声明numpy依赖即可，meson会自动查找头文件路径：

py = import('python').find_installation(pure: false)
numpy_dep = dependency('numpy')

py.extension_module(
    'your_ext_module',
    'src/your_ext.c',
    dependencies: [py.dependency(), numpy_dep],
    install: true
)

• 如果用scikit-build作为构建后端，直接在CMake脚本中查找Python的NumPy组件，会自动注入正确的头文件搜索路径。

这个方案是Python C扩展引用numpy头文件的标准做法，不需要针对cibuildwheel做任何特殊配置，本地开发、CI构建、用户源码编译全场景通用。

如果因为特殊历史原因无法修改构建脚本，必须通过C_INCLUDE_PATH传递头文件路径，就把动态获取路径、设置环境变量的逻辑放到before-build步骤中——这个步骤的执行时机是每个版本的wheel构建前，此时隔离构建环境已经创建完成，所有构建依赖（包括numpy）都已经安装完毕，可以正常调用numpy获取路径。注意不同平台的shell语法存在差异，建议分平台配置避免兼容问题：

[tool.cibuildwheel.linux]
before-build = "export C_INCLUDE_PATH=$(python -c 'import numpy; print(numpy.get_include())'):$C_INCLUDE_PATH"

[tool.cibuildwheel.macos]
before-build = "export C_INCLUDE_PATH=$(python -c 'import numpy; print(numpy.get_include())'):$C_INCLUDE_PATH"

[tool.cibuildwheel.windows]
before-build = "set C_INCLUDE_PATH=%C_INCLUDE_PATH%;`python -c \"import numpy; print(numpy.get_include())\"`"

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