使用cibuildwheel构建Python跨平台wheel的经验分享

背景介绍

cibuildwheel是一个强大的工具，用于在CI环境中为Python项目构建跨平台的wheel包。近期在为一个名为libqasm的项目配置构建系统时，遇到了一些典型问题，本文将分享这些问题的解决方案。

常见问题及解决方案

1. 依赖工具无法找到的问题

在Linux环境下，cibuildwheel会在manylinux容器中执行构建，因此系统PATH环境变量会被重置。如果项目构建依赖于Conan等工具，需要显式安装：

[tool.cibuildwheel.linux]
before-all = "pip install conan"

2. 平台架构相关问题

Windows平台32/64位问题： 当发现构建意外生成了32位(win32)而非预期的64位wheel时，可以通过配置禁用32位构建：

[tool.cibuildwheel]
skip = "*-win32"

Linux ARM架构支持： 要为aarch64架构构建wheel，需要配置QEMU模拟器支持：

jobs:
  build_wheels:
    runs-on: ubuntu-latest
    services:
      qemu:
        image: multiarch/qemu-user-static
        options: --privileged

3. 构建系统现代化

虽然setup.py文件本身并未被弃用，但直接调用python setup.py的方式已被标记为不推荐。现代Python打包应优先使用pyproject.toml配合构建后端(如setuptools)的方式。

可以移除setup.py中过时的命令如bdist(用于生成egg格式)，专注于bdist_wheel构建。

最佳实践建议

1. 环境隔离：在CI环境中，确保所有构建依赖都通过before-all脚本显式安装

2. 架构明确：仔细检查目标平台架构，必要时通过skip选项过滤不需要的架构

3. 构建系统更新：逐步将setup.py中的逻辑迁移到pyproject.toml中，使用现代构建规范

4. 测试验证：构建完成后，应在对应平台上测试wheel是否正常工作

通过合理配置cibuildwheel，可以高效地为项目生成跨平台的二进制分发包，大大简化用户安装过程。