如何在Linux服务器（GitLab CI）上构建ARM macOS版Python Wheel？

可以在Linux服务器（如GitLab CI）上构建ARM架构macOS的Python Wheel包，最简便可靠的方式是使用cibuildwheel工具，它专门针对跨平台Wheel构建做了优化，支持通过Docker容器在Linux环境下完成ARM macOS的交叉编译。

具体操作步骤 #

1. 环境前提 #

确保GitLab CI Runner支持Docker（大部分共享Runner默认已开启），cibuildwheel需要通过容器获取ARM macOS的交叉编译工具链。

2. 编写GitLab CI配置 #

在项目根目录创建.gitlab-ci.yml文件，示例配置如下：

build-macos-arm64-wheel:
  image: python:3.12-slim
  stage: build
  variables:
    # 指定目标平台为ARM架构macOS
    CIBW_PLATFORMS: "macos_arm64"
    # 筛选要构建的Python版本（可按需调整）
    CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-*"
    # 使用官方交叉编译镜像
    CIBW_MACOS_ARM64_IMAGE: "quay.io/pypa/macos-cross-arm64:latest"
  before_script:
    - pip install --upgrade pip
    - pip install cibuildwheel
  script:
    # 执行构建，生成的Wheel输出到wheelhouse目录
    - cibuildwheel --output-dir wheelhouse .
  artifacts:
    paths:
      - wheelhouse/*.whl
    expire_in: 1 week

3. 关键配置说明 #

• CIBW_PLATFORMS: 明确指定目标平台，macos_arm64对应ARM架构的macOS
• CIBW_BUILD: 筛选支持的Python版本，格式为cp{版本号}-*，比如cp310-*表示所有Python3.10的平台包
• CIBW_MACOS_ARM64_IMAGE: 官方提供的交叉编译镜像，已预装Xcode工具链和交叉编译依赖

4. 处理含C扩展的项目 #

如果项目包含C/C++扩展代码，cibuildwheel会自动调用交叉编译器完成编译。若依赖系统级第三方库，可通过CIBW_BEFORE_BUILD变量添加预安装命令：

variables:
  # 构建前安装依赖库
  CIBW_BEFORE_BUILD: "brew install libyaml"

（注：macos-cross-arm64镜像内置Homebrew，可直接使用brew命令）

5. 验证构建结果 #

构建完成后，wheelhouse目录下会生成带有macosx_arm64标签的Wheel包，例如your_package-1.0.0-cp312-cp312-macosx_11_0_arm64.whl。

可通过以下命令验证Wheel的平台兼容性：

# 安装pip-tools
pip install pip-tools
# 检查Wheel元数据
pip wheel inspect wheelhouse/your_package-*.whl

输出中会显示Tag: cp312-cp312-macosx_11_0_arm64，确认平台匹配。

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