根本原因是wheel包未包含当前系统架构的C扩展二进制文件；正确做法是用auditwheel/delvewheel/macos-platform-tag适配平台标签，并通过CI交叉构建多平台wheel，同时在setup.py中动态控制编译行为。
为什么 pip install 时 C 扩展总报错“no matching distribution”
根本原因不是代码写错了，而是 wheel 包里没包含当前系统的 C 扩展二进制文件。Python 的 bdist_wheel 默认只打包当前构建机器的平台标签（如 cp39-cp39-manylinux_2_17_x86_64），跨系统（Windows/macOS/Linux）或跨架构（x86_64/aarch64）就直接找不到匹配项。
如何让 setup.py 生成多平台 wheel
不能靠本地反复切换系统打包——效率低、易漏、不一致。正确路径是用 auditwheel（Linux）、delvewheel（Windows）、macos-platform-tag（macOS）做平台适配，再配合 CI 工具交叉构建：
- Linux：在
manylinux2014或manylinux_2_17容器中运行python -m build --wheel，再用auditwheel repair补全依赖 - Windows：用 GitHub Actions 的
windows-latest环境，确保安装了对应版本的 Visual Studio Build Tools，setup.py中显式声明ext_modules并设define_macros=[('PYWIN32', None)]避免宏冲突 - macOS：必须区分
universal2和arm64/x86_64单架构；在 Apple Silicon 上用ARCHFLAGS="-arch arm64" python -m build，再用macos-platform-tag重打标签
setup.py 里怎么控制 C 扩展编译行为
setuptools 的 Extension 构造函数本身不支持条件编译，得靠环境变量 + 自定义 build_ext 子类绕过：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
os.getenv("PY_EXT_PLATFORM")控制是否启用某段Extension，比如只在 Linux 启用libfuse绑定 - 避免硬编码
libraries=["pthread"]—— macOS 不认pthread，应改用extra_link_args=["-pthread"]并在build_ext.run()里按sys.platform动态追加 - 若扩展依赖第三方 C 库（如 OpenSSL），不要在
setup.py里写死library_dirs=["/usr/local/opt/openssl/lib"]，改用PkgConfig或find_library动态探测
CI 配置里最容易被忽略的三个点
GitHub Actions / GitLab CI 脚本看着跑通，但上传到 PyPI 后用户仍装不上，问题常出在这三处：
立即学习“Python免费学习笔记（深入）”；
- 忘记给 wheel 打上正确的
Platform Tag：Linux 必须用manylinux标签，不能留默认的linux_x86_64；检查命令：python -c "import wheel.bdist_wheel; print(wheel.bdist_wheel.get_platform())" - Windows 上未清理
build/和__pycache__/就重新构建，导致旧的.obj文件残留，链接时符号重复或缺失 - macOS 上没禁用 SIP 对
/usr/lib的拦截，导致auditwheel类工具失效；正确做法是全程在venv内操作，且不调用系统级install_name_tool
平台标签一旦打错，PyPI 就当它是“不兼容 wheel”，连 pip install --only-binary=:all: 都不会选它。这点没有容错，修完必须手动验证 pip debug --verbose 输出里的 compatible_tags 是否覆盖目标环境。
