PyProject.toml：现代Python项目打包配置的核心指南
在Python的打包与分发领域，pyproject.toml 文件已成为无可争议的现代标准配置方案。整个Python打包生态系统，包括主流的 setuptools 构建工具，都已全面转向并推荐使用此文件。如果你仍在直接编写和维护传统的 setup.py 脚本，需要特别注意——这种模式不仅已经过时，而且在 pip ≥23.1 及最新版 build 工具中，很可能会触发弃用警告，甚至直接导致项目构建失败。
第一步：在 pyproject.toml 中声明构建后端
许多开发者在第一步就遇到阻碍：执行 python -m build 命令时，系统报错 ModuleNotFoundError: No module named 'setuptools.build_meta'，或提示“未指定构建后端”。其根本原因在于缺少了关键的 [build-system] 配置段落。
- 必须在
[build-system]段落中，明确声明build-backend = "setuptools.build_meta"。 requires列表里必须至少包含"setuptools>=61.0"（此版本开始完整支持PEP 621标准）和"wheel"（用于生成标准的 .whl 二进制分发包）。- 若计划采用
setuptools_scm工具来自动化管理项目版本号，则需在requires列表中额外添加"setuptools-scm[toml]>=8.0"。
[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"
第二步：采用PEP 621标准配置项目元数据（完全替代setup.py）
现在，你不再需要编写 setup.py 或 setup.cfg 文件。所有项目核心信息都应统一写入 [project] 段落，这是 setuptools 61.0 及以上版本原生支持的现代化配置方式。
name（包名）、version（版本）、description（描述）、readme（自述文件）、requires-python（Python版本要求）是必须填写的核心字段。dependencies字段替代了旧的install_requires，其格式为字符串列表，并完整支持PEP 508依赖规范（例如条件依赖："requests>=2.25; platform_system != 'Windows'"）。optional-dependencies对应原有的extras_require，用于定义可选依赖组。键名即为 extra 的名称（如dev、test），值是对应的依赖包列表。- 一个关键细节：如果你打算使用
setuptools_scm自动从__version__变量或 Git 标签提取版本号，则必须删除[project]中的version字段，否则两者会发生冲突。
[project] name = "mylib" version = "0.1.0" description = "A sample package" readme = "README.md" requires-python = ">=3.8" dependencies = ["requests>=2.25"] [project.optional-dependencies] dev = ["pytest>=7.0", "black"]
第三步：配置动态版本管理（setuptools_scm 使用详解）
手动维护 version 字段极易出错且繁琐。setuptools_scm 能够基于 Git 提交历史或标签自动生成语义化版本号，极大提升效率，但其配置有一些特定要求，忽略则可能导致功能失效。
立即学习“Python免费学习笔记（深入）”；
- 首先，确保项目根目录是一个有效的 Git 仓库（包含
.git/目录），并且至少存在一个符合语义化版本规范的标签（例如v0.1.0或1.2.3）。 - 在
[build-system]的requires列表中加入"setuptools-scm[toml]>=8.0"。 - 务必删除
[project]段落中的version字段，这是激活setuptools_scm自动版本管理功能的前提条件。 - 如需自定义版本生成行为，可添加
[tool.setuptools_scm]配置段落。例如，设置回退版本：fallback_version = "0.0.0"；或禁用本地版本节点：local_scheme = "no-local-version"。
执行打包命令与常见问题解决方案
运行 python -m build 命令，默认会同时生成源码分发包（sdist，格式为 .tar.gz）和二进制分发包（wheel，格式为 .whl）。但在实际的持续集成与部署流程中，我们往往需要精确控制输出类型，或跳过某些步骤。
- 仅构建 wheel 包：
python -m build --wheel；仅构建源码包：python -m build --sdist。 - 若遇到报错
error: invalid command 'bdist_wheel'，这通常意味着wheel包未被正确添加到build-system.requires依赖列表中。 - 打包完成后，强烈建议使用
twine check dist/*命令检查生成分发包的元数据是否符合 PyPI 规范。注意，并非所有警告都需要处理，但像InvalidDistribution这类错误必须修复后才能上传。 - 在将包上传至 PyPI 之前，务必确认
project.urls（项目链接）、project.authors（作者信息）等字段均已完整填写。缺少必要描述或作者信息的包会被 PyPI 仓库直接拒绝上传。
最后，分享两个最容易被开发者忽略的关键陷阱。首先是 Git 仓库状态：setuptools_scm 默认要求工作目录是干净的（即没有未提交的更改），否则它可能会静默地回退到配置的 fallback_version。你需要在 [tool.setuptools_scm] 中显式设置 dirty = true 来允许“脏”提交状态下的版本生成。其次，文件位置至关重要：pyproject.toml 必须放置在项目的根目录下，并且确保它没有被 MANIFEST.in 文件排除（当然，在现代的 PEP 621 配置范式下，大多数项目已不再需要手动编写 MANIFEST.in 文件）。
