直接用setuptools+build就能打出标准Wheel，无需setup.py；需pyproject.toml声明[build-system]和[project]，src布局需与project.name一致，运行python -m build生成.whl。
直接用 setuptools + build 就能打出标准 Wheel，不需要手动写 setup.py（除非你真有特殊需求）。
确认项目结构符合 PEP 517 要求
Wheel 打包依赖现代 Python 构建后端，要求项目根目录下存在 pyproject.toml。没有这个文件，python -m build 会报错或回退到旧模式，结果不可控。
- 最简
pyproject.toml至少要声明构建系统：[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"] build-backend = "setuptools.build_meta"
- 包名、版本、依赖等信息应写在
[project]段下，不是setup.py；若仍保留setup.py，它会被忽略（除非显式指定--legacy） -
src/目录布局需与project.name一致，比如project.name = "mylib"，则源码应放在src/mylib/下
运行 python -m build 生成 wheel
这是目前最可靠、最接近“开箱即用”的方式，它自动处理元数据、编译扩展、平台标记等细节。
- 确保已安装最新版
build：pip install --upgrade build - 在项目根目录执行：
python -m build（默认同时生成.tar.gz和.whl） - 只打 wheel：
python -m build --wheel；输出在dist/目录下，文件名含平台标签，如mylib-0.1.0-py3-none-any.whl - 如果项目含 C 扩展，需提前装好对应平台的编译工具链（如 Windows 的 Visual Studio Build Tools，macOS 的 Xcode Command Line Tools），否则
build会卡在编译步骤
验证 wheel 是否可被 pip 正确识别
打包完别急着上传，先本地验证 wheel 是否“干净”——能否被 pip 安装、导入、运行基础功能。
- 检查 wheel 元数据：
python -m wheel unpack dist/*.whl，看mylib-0.1.0.dist-info/METADATA是否包含正确字段（Name,Version,Requires-Dist） - 临时创建干净环境测试安装：
python -m venv .testenv && .testenv/bin/python -m pip install dist/*.whl（Windows 用.testenv\Scripts\python.exe） - 常见失败点：
ImportError: No module named 'mylib'多因project.name和实际包目录名不一致；ModuleNotFoundError在安装后出现，说明packages或package-dir配置漏了src/前缀
真正容易被忽略的是平台兼容性标记：纯 Python 包默认打成 py3-none-any.whl，但一旦用了 ctypes 加载动态库，或写了 pyproject.toml 里带 [project.optional-dependencies] 却没声明 requires-python，wheel 就可能在目标环境静默失败——得靠 pip debug --verbose 看解释器 tag 匹配逻辑。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
