如何为各平台创建专属Python Wheel并仅包含对应平台二进制文件

1. 项目结构调整建议 #

先整理成更适配构建流程的结构，保留原平台二进制文件夹，构建时动态复制到通用目录：

project
├── your_package/          # 你的Python代码包
│   ├── __init__.py
│   └── core.py            # 代码中直接调用通用bin目录下的二进制
├── binaries/
│   ├── win32/
│   ├── win64/
│   ├── linux32/
│   ├── linux64/
│   ├── linuxarm/
│   ├── darwin64/
│   └── darwinarm/
├── pyproject.toml         # 现代构建配置文件
└── setup.py               # 构建逻辑脚本

2. 核心构建逻辑实现 #

利用Python的sysconfig识别当前平台，动态复制对应二进制到通用目录your_package/bin，同时生成带平台标记的专属Wheel。

配置pyproject.toml #

先声明构建依赖：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

编写setup.py实现动态复制 #

import os
import shutil
from sysconfig import get_platform
from setuptools import setup

# 映射Python平台标记到你的二进制文件夹名称
PLATFORM_BIN_MAP = {
    "win32": "win32",
    "win-amd64": "win64",
    "linux-i686": "linux32",
    "linux-x86_64": "linux64",
    "linux-aarch64": "linuxarm",
    "macosx-x86_64": "darwin64",
    "macosx-arm64": "darwinarm",
}

# 构建前自动复制对应平台二进制到通用目录
current_platform = get_platform()
src_bin_dir = os.path.join("binaries", PLATFORM_BIN_MAP[current_platform])
target_bin_dir = os.path.join("your_package", "bin")

# 清理旧目录并复制新文件
if os.path.exists(target_bin_dir):
    shutil.rmtree(target_bin_dir)
shutil.copytree(src_bin_dir, target_bin_dir)

setup(
    name="your-package-name",
    version="0.1.0",
    packages=["your_package"],
    # 打包时包含通用目录下的二进制文件
    package_data={
        "your_package": ["bin/*"],
    },
    # 声明为平台专属Wheel，不生成纯Python包
    options={
        "bdist_wheel": {
            "universal": False,
        }
    },
)

3. 构建Wheel #

运行以下命令生成对应平台的Wheel：

python -m build

构建完成后，dist/目录下会生成类似your_package-name-0.1.0-cp310-cp310-linux_x86_64.whl的平台专属包，用unzip查看内部结构，会发现仅包含当前平台的二进制文件，且已统一放在your_package/bin/目录下。

4. 代码中调用二进制 #

在Python代码里直接引用通用路径即可，无需判断平台：

from pathlib import Path

# 获取二进制文件路径
binary_path = Path(__file__).parent / "bin" / "your-binary-file"

# 调用二进制（示例）
import subprocess
subprocess.run([str(binary_path)], check=True)

5. 批量构建多平台Wheel（可选） #

如果需要在单台机器上生成所有平台的Wheel，可以用cibuildwheel工具，它会通过Docker或虚拟机自动完成跨平台构建，只需配置cibuildwheel.toml指定目标平台，上述复制逻辑会自动在各平台构建流程中执行。

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