Python打包元数据标准化后的构建流水线调整方法

Python 打包配置正在从“每个工具一套写法”转向更清晰的分层：pyproject.toml 里的 [project] 负责项目元数据，[build-system] 负责构建后端，[tool] 保留工具私有配置。调整流水线时，重点不是把所有配置机械搬家，而是先让元数据、构建和发布各自只有一个责任边界。

官方资料入口：https://packaging.python.org/　规范原文：https://peps.python.org/pep-0621/

先把三类配置分开，迁移才不会反复返工

旧项目通常同时存在 setup.py、setup.cfg、pyproject.toml 和 CI 脚本。第一步先做一张映射表：包名、版本、依赖、Python 版本范围、入口点属于项目元数据；构建后端名称和构建依赖属于构建系统；lint、测试覆盖率或格式化工具的开关属于 [tool.*]。

PEP 621 规定，[project] 中直接写出的静态值是规范值，后端不能悄悄改写；只有列在 dynamic 中的字段才交给后端补充。因此，不要为了保留旧脚本的“自动读版本”习惯，把所有字段都声明成动态。

用 pyproject.toml 固定构建后端与核心元数据

一个采用 setuptools 后端的迁移起点如下。注释只说明字段职责，依赖版本应结合项目支持范围锁定：

[build-system]
# 构建隔离环境先安装这些依赖，再调用后端生成产物
requires = ["setuptools>=77.0.3"]
build-backend = "setuptools.build_meta"

[project]
# 这些字段是发布给索引和安装工具读取的核心元数据
name = "sample-library"
version = "2.4.0"
description = "A small example library"
readme = "README.md"
requires-python = ">=3.9"
dependencies = ["httpx>=0.27"]

[tool.pytest.ini_options]
# 工具私有配置放在自己的命名空间，避免污染 [project]
addopts = "-q"

版本如果仍由 SCM 或后端计算，应改成 dynamic = ["version"]，并确认该后端确实提供版本；否则构建时会出现“元数据缺失”，而不是由上传工具修复。许可证、入口点和可选依赖也要逐项迁移，不要把旧配置文件继续作为第二个事实源。

调整流水线：构建、检查、上传各做一件事

标准化元数据后，CI 可以拆成三个稳定阶段。先在隔离环境构建，再只检查 dist/ 中的文件名、版本和元数据，最后交给上传工具：

# 构建 sdist 和 wheel；命令只负责生成发布产物
python -m build

# 检查产物目录，上传阶段不要重新从源码猜版本
python -m twine check dist/*

# 通过仓库凭据上传已经检查过的产物
python -m twine upload dist/*

Python Packaging User Guide 将 build 作为生成 sdist 和 wheel 的标准工具，并把 twine 放在上传阶段。这样做的好处是：后端可以替换，产物检查规则不变；仓库从 TestPyPI 切换到 PyPI 时，也只改发布凭据和目标配置。

迁移验收清单与容易踩的边界

常见问题

迁移到 pyproject.toml 后还要删除 setup.py 吗？

不必立即删除。若项目仍需要程序化配置或扩展模块，可以保留它；但同一个元数据字段应只保留一个权威来源，避免构建后端读取结果不一致。

为什么写了 version 还提示版本缺失？

检查后端是否把该字段声明为动态、版本插件是否在 build-system.requires 中可用，以及 CI 是否在正确的源码根目录执行构建。

发布前一定要同时生成 sdist 和 wheel 吗？

对需要兼容不同平台或安装环境的库，通常应同时提供两者；纯 Python 包的 wheel 较简单，含原生扩展时还要按 Python、系统和架构准备对应 wheel。