不能靠 setup.py 自动判断 OS 并切换编译逻辑，因其 platform.system() 返回构建平台而非目标平台，且违反 PEP 517 可重现性要求；应改用 pyproject.toml 配合 scikit-build-core 等后端做平台预设配置，或在 CI/CD 中按平台分离构建任务。

直接结论：不能靠 setup.py 自动判断 OS 并切换编译逻辑 —— 它在构建时只运行一次，且目标平台不等于构建平台；真正可靠的方式是用 pyproject.toml + 构建后端（如 setuptools 或 scikit-build-core）配合条件性配置，或在 CI/CD 中按平台分发独立构建任务。

为什么 setup.py 的 platform.system() 在跨平台打包中不可信

很多人在 setup.py 里写 if platform.system() == "Windows" 来加 extra_compile_args，这看似合理，但实际会出问题：

• 你在 macOS 上运行 pip wheel . 构建一个 Windows 轮子（比如交叉编译），platform.system() 返回的是 "Darwin"，不是目标平台
• PyPI 不接受包含平台判断逻辑的 setup.py —— 它必须是纯声明式、可重现的
• PEP 517 规定构建过程必须隔离，setup.py 运行环境 ≠ 最终用户环境

正确做法：用 pyproject.toml 声明平台感知的构建配置

现代 Python 构建依赖 pyproject.toml，它支持通过 [tool.setuptools] 或 [tool.scikit-build] 指定条件性行为。关键不是“自动检测”，而是“为每个平台预设好构建路径”：

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 对 pybind11 项目，推荐用 scikit-build-core：

  [build-system]
  requires = ["scikit-build-core>=0.10", "pybind11"]
  build-backend = "scikit_build_core.build"
  <p>[project]
  name = "mylib"
  requires-python = ">=3.8"</p><p>[tool.scikit-build]
  wheel = {plat-name = "manylinux2014_x86_64"}  # 显式指定目标平台标识</p><p>[tool.scikit-build.cmake]
  args = [
  "-DPYBIND11_FINDPYTHON=ON",
  "-DCMAKE_BUILD_TYPE=Release",
  ]</p><h1>Windows 下启用 /MD 链接，Linux/macOS 用 -fPIC</h1><p>[tool.scikit-build.cmake.configure-settings]
  CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS = true
  CMAKE_POSITION_INDEPENDENT_CODE = true

• 若坚持用 setuptools，则通过 setup.cfg 或 pyproject.toml 的 [tool.setuptools.ext-modules] 块定义多个 Extension，再用 build_ext 子类覆盖 build_extensions 方法 —— 但该方法已被标记为 deprecated，不推荐新项目使用

CI/CD 中必须按平台分离构建任务

真实发布流程中，你不会在一台机器上“自动适配所有系统”，而是分别触发：

立即学习“Python免费学习笔记（深入）”；

• GitHub Actions：用 strategy.matrix 分开跑 ubuntu-latest、macos-latest、windows-latest
• 每个 job 设置明确的 python-version 和 arch，并传入对应 CMake 工具链文件（如 toolchain-aarch64-linux-gnu.cmake）
• Linux wheel 必须用 manylinux 容器（如 quay.io/pypa/manylinux2014_x86_64），否则生成的 .so 会因 GLIBC 版本过高而无法在旧系统运行
• Windows 上注意：MSVC 运行时要统一（/MD），且避免混用 MinGW 和 MSVC 编译的模块

容易被忽略的关键点

最常被跳过的其实是 ABI 兼容性验证：

• auditwheel（Linux）、delvewheel（Windows）、macosx-fix-wheel（macOS）必须在构建后运行，否则 wheel 可能漏掉动态库依赖
• C++ 扩展若用了 STL 容器（如 std::string）导出符号，不同编译器 STL 实现不兼容 —— 应始终开启 PYBIND11_STABLE_ABI 或用 nanobind 替代
• Python 解释器头文件路径在交叉编译时极易出错，find_package(Python) 必须显式指定 Python_ROOT_DIR，不能依赖默认探测