打包失败主因是环境、配置或元数据未对齐：setup.py中find_packages()未匹配src目录结构、abi标签与python解释器不一致、install_requires未正确声明致依赖缺失，wheel文件名中的平台/abi标签即为构建环境指纹。
打包失败不是代码问题，而是环境、配置或元数据没对齐。 大多数 bdist_wheel 报错根本原因不在你的 Python 代码，而在 setup.py 或构建环境与目标平台的隐含约定不一致。
setup.py 中的 packages 和 package_dir 容易写反
常见现象是生成的 .whl 文件里缺模块，或者安装后 import 报 ModuleNotFoundError。这不是 pip 没装好，而是 setuptools 没找到你要打包的目录。
- 如果你项目结构是
src/mylib/__init__.py，但setup.py写了packages=find_packages()，它默认从当前目录找，会漏掉src下的内容 - 正确做法是显式指定：
package_dir={"": "src"}，再配合packages=find_packages("src") - 如果用
pyproject.toml（推荐），需在[build-system]下声明构建器，并在[project]中用packages = [{include = "mylib", from = "src"}]
编译 C 扩展时 missing wheel tag 或 abi 不匹配
报错如 error: invalid command 'bdist_wheel' 或生成的 .whl 名字里出现 cp39-cp39m-linux_x86_64.whl，但在另一台机器上被拒绝安装——本质是 ABI 标签和 Python 解释器实际 ABI 不一致。
- 检查当前 Python 的 ABI：运行
python -c "import sysconfig; print(sysconfig.get_config_var('SOABI'))"，输出应为cp39或cp39-cp39m等 - 若你用的是系统 Python（尤其 CentOS/RHEL），可能启用了
--with-pymalloc，导致 ABI 是cp39m；而你本地 miniconda 的 Python 是cp39，二者不兼容 - 解决方案不是“改文件名”，而是统一构建环境：用
conda create -n build-env python=3.9，再在该环境中运行pip install wheel && python -m build
依赖声明写在 setup.py 里却没生效
打包成功，但别人 pip install xxx.whl 后运行时报 ImportError: No module named requests——说明依赖没进元数据，pip 安装时根本没拉。
-
install_requires必须写在setup()调用里，不能只写在requirements.txt中 - 若用
pyproject.toml，必须把依赖写在[project.dependencies]下，而非[build-system]或随便哪个 section - 避免用
dependency_links或-e git+...这类非标准写法，它们不会被 wheel 元数据收录 - 验证方式：解压生成的
.whl，打开xxx-*.dist-info/METADATA，搜索Requires-Dist:行，确认依赖已列出
真正麻烦的从来不是“怎么打包”，而是“打包出来的 wheel 是否能被别人干净地装上”。最常被忽略的点是：你本地构建环境的 Python ABI、平台标签、甚至 setuptools 版本，都会直接刻进 wheel 文件名和元数据里——它不是黑盒，而是带指纹的交付物。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
