如何在GitHub流水线中配置QEMU构建ARM64（AArch64）Linux Wheel？

配置步骤 #

cibuildwheel在GitHub Actions环境下支持通过QEMU模拟构建AArch64 Linux版本，以下是具体配置方案：

1. 流水线中安装并启用QEMU #

在GitHub Actions的构建job里，先通过官方action配置QEMU，再执行cibuildwheel构建：

jobs:
  build_wheels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # 安装QEMU以支持跨架构模拟
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      # 安装cibuildwheel
      - name: Install cibuildwheel
        run: python -m pip install cibuildwheel
      # 执行AArch64架构构建
      - name: Build AArch64 wheels
        run: python -m cibuildwheel --output-dir wheelhouse
        env:
          # 指定Linux平台仅构建AArch64架构
          CIBW_ARCHS_LINUX: aarch64

2. 验证QEMU有效性（可选） #

若需要确认QEMU是否正常工作，可在构建前添加验证步骤：

docker run --rm --platform linux/arm64/v8 alpine uname -m

输出aarch64则表示跨架构模拟已生效。

3. 多架构构建扩展 #

如果需要同时构建x86_64原生架构和AArch64模拟架构，只需调整环境变量：

env:
  CIBW_ARCHS_LINUX: auto aarch64

auto会触发原生x86_64构建，aarch64则通过QEMU模拟执行。

注意事项 #

• 大部分官方Python基础镜像已适配QEMU模拟，无需额外修改镜像配置
• GitHub Actions的ubuntu-latest环境默认提供Docker权限，无需额外配置sudo或用户权限

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