如何通过build与pyproject.toml强制生成平台专属wheel包？

问题描述 #

我正在构建一个Python 3包，其中包含操作系统专属的共享库（.so/.dylib/.dll），这些库由独立构建系统提前生成并复制到包目录中，Python包本身没有原生构建步骤。我需要根据构建主机的操作系统，生成对应平台的Wheel包（如manylinux、macOS或Windows版本），但使用python3 -m build --wheel命令时，始终生成mypackage-0.1-py3-none-any.whl这种通用包。此前用废弃的setup.py方案有解决办法，但不清楚如何通过当前标准的pyproject.toml系统实现相同效果。

包结构如下：

mypackage/
  mypackage.py  # 通过platform.system和importlib加载本地平台专属库
  pyproject.toml
  mysharedlib.so  # macOS为.dylib，Windows为.dll

解决方案 #

1. 配置build-system与包数据 #

首先确保pyproject.toml使用setuptools作为构建后端，并配置package-data包含平台专属共享库：

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

[project]
name = "mypackage"
version = "0.1"
authors = [{"name" = "Your Name", "email" = "your@email.com"}]
description = "Platform-specific package with pre-built shared library"

[tool.setuptools.package-data]
mypackage = ["*.so", "*.dylib", "*.dll"]

2. 强制生成平台专属标签 #

由于包无原生扩展，setuptools默认会生成通用any标签，需要手动指定平台信息，有两种实现方式：

方式一：动态匹配构建平台（推荐）

在构建时通过环境变量PLAT_NAME指定当前平台，setuptools会自动生成对应标签：

PLAT_NAME=$(python -c "import setuptools; print(setuptools.command.build_py.get_platform())") python3 -m build --wheel

该命令会根据构建主机自动生成对应平台的标签，比如在Linux上生成manylinux_2_17_x86_64，macOS上生成macosx_10_15_x86_64，Windows上生成win_amd64。

方式二：静态配置平台标签（适合固定构建环境）

如果构建环境固定，可以直接在pyproject.toml中指定bdist_wheel的平台名称：

[tool.setuptools.options.bdist_wheel]
# 替换为你的目标平台，比如Linux用manylinux_2_17_x86_64，macOS用macosx_10_15_x86_64，Windows用win_amd64
plat-name = "manylinux_2_17_x86_64"

这种方式会固定生成指定平台的Wheel包，适用于单一环境的构建场景。

3. 验证结果 #

构建完成后，检查生成的Wheel文件名，应该包含对应的平台标签，比如：

• Linux: mypackage-0.1-py3-none-manylinux_2_17_x86_64.whl
• macOS: mypackage-0.1-py3-none-macosx_10_15_x86_64.whl
• Windows: mypackage-0.1-py3-none-win_amd64.whl

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