如何搭建Python项目自动化打包流程_配置Setuptools与PyProject

PyProject.toml：现代Python打包的基石

在Python打包领域，pyproject.toml 已经成为事实上的标准。整个生态，包括 setuptools 本身，都已全面转向基于此文件的配置方式。如果你还在直接编写 setup.py，那可要注意了——这种做法不仅已经过时，而且在 pip ≥23.1 及最新版本的 build 工具中，很可能会触发警告，甚至直接导致构建失败。

第一步：在 pyproject.toml 中声明构建后端

很多项目在第一步就卡住了：运行 python -m build 时，报错 ModuleNotFoundError: No module named 'setuptools.build_meta'，或者提示“no build backend specified”。问题的根源很简单：缺少了关键的 build-backend 声明。

• 必须在 [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 是必填项。
• dependencies 字段替代了旧的 install_requires，格式是字符串列表，并且支持完整的PEP 508表达式（例如 "requests>=2.25; platform_system != 'Windows'"）。
• optional-dependencies 对应原来的 extras_require，键名就是 extra 的名称（比如 dev），值是对应的依赖列表。
• 这里有个关键点：如果你想启用 setuptools_scm 来自动从 __version__ 或 Git tag 提取版本，就必须删除这里的 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 commit 或 tag 自动生成版本号，非常方便，但配置上有些细节需要注意，否则很容易失效。

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

• 首先，确保项目根目录是一个 Git 仓库（包含 .git/ 目录），并且至少有一个带有语义化标签的 commit（例如 v0.1.0）。
• 在 [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）。但在实际的 CI/CD 流程中，我们常常需要控制输出类型，或者跳过某些步骤。

• 只构建 wheel：python -m build --wheel；只构建源码包：python -m build --sdist。
• 如果遇到报错 error: invalid command 'bdist_wheel'，这通常意味着 wheel 包没有被列在 build-system.requires 中。
• 打包完成后，建议用 twine check dist/* 检查包的元数据是否合规。注意，不是所有警告都是致命的，但像 InvalidDistribution 这类错误必须修复。
• 上传到 PyPI 前，务必确认 project.urls、project.authors 等字段都已填写。一个没有描述或作者信息的包，是会被 PyPI 直接拒绝的。

最后，分享两个最容易被忽略的陷阱。首先是 Git 仓库的状态：setuptools_scm 默认要求工作区是干净的（没有未提交的更改），否则它可能会静默地回退到 fallback_version。你需要在配置中显式允许“脏”提交（dirty = true）来避免这个问题。其次，文件位置也很关键：pyproject.toml 必须放在项目的根目录下，并且不能被 MANIFEST.in 排除（当然，在现代配置下，大多数项目已经不再需要 MANIFEST.in 文件了）。