Python packaging 从 setup.py 迁移 pyproject.toml 的清单

我处理旧 Python 项目时，迁移 packaging 配置最容易踩的坑不是 TOML 语法，而是把“构建后端”“项目元数据”和“仍然需要执行的 Python 逻辑”混成一件事。比较稳妥的做法是先加上 pyproject.toml 的 [build-system]，再把稳定的元数据搬到 [project]，最后逐项确认包发现、动态版本和构建命令。setup.py 不必当天删除，但不应再用 python setup.py install 这类直接调用。

setup.py 中哪些内容应该搬进 pyproject.toml

先把旧文件拆成四类：项目名称、版本、README、依赖属于元数据；构建时需要的 setuptools 或插件属于构建依赖；包目录发现属于后端配置；读取 Git 标签、生成版本或编译扩展的 Python 逻辑则可能继续动态存在。

先建立 [build-system]，再决定 setup.py 是否保留

对 Setuptools 项目，根目录可以先放一个最小配置。requires 不是运行时依赖，而是构建隔离环境需要的依赖；如果版本计算函数还导入了第三方库，也要把它写进去。

[build-system]
requires = ["setuptools"] # 声明构建阶段必须安装的后端
build-backend = "setuptools.build_meta" # 让前端调用 Setuptools 的标准接口

[project]
name = "example-package" # 分发名称，保持与旧包一致
version = "1.2.3" # 能静态确定时直接写入
readme = "README.md" # README 作为长描述来源
dependencies = ["requests>=2.31"] # 使用 PEP 508 依赖表达式

如果版本必须从 Git 标签或源码常量得到，可以写 dynamic = ["version"]，并保留后端支持的动态配置。若外部脚本仍执行 python setup.py --name，保留一个很薄的 setup.py 是兼容策略，不代表要继续用它来安装和打包。

包发现和依赖迁移要做一次对照

迁移后最隐蔽的失败是“构建成功但 wheel 里没有子包”。src 布局、命名空间包、额外数据文件都要按 Setuptools 当前配置重新核对，不要把原来的 find_packages() 直接当成标准元数据。依赖也要区分运行时依赖与构建依赖：前者进 [project].dependencies，后者进 [build-system].requires。

[tool.setuptools.packages.find]
where = ["src"] # 只有 src 布局时才指定源码根目录

[tool.setuptools.package-data]
example_package = ["templates/*.json"] # 把运行时需要的非 Python 文件纳入包

这里的表名属于 Setuptools 后端，不要因为看到 [project] 就把所有配置都塞进去。配置完成后检查构建产物的文件清单，尤其是入口脚本、模板和子包。

构建、安装和回归检查要分开验证

官方迁移建议把直接执行 setup.py 的命令换成现代前端命令。实际回归时我会把“能生成文件”和“安装后能用”分开：

python -m build # 构建 sdist 与 wheel，不直接执行 setup.py
python -m pip install . # 在隔离环境验证普通安装
python -m pip install --editable . # 验证开发态导入和入口

检查 dist/ 中是否同时有源码分发包和 wheel，再在干净虚拟环境里验证导入、命令入口、依赖版本和 README 元数据。若只在当前源码目录中 import 成功，不能证明 wheel 内容完整。

常见问题

迁移 pyproject.toml 后必须删除 setup.py 吗？

不必须。兼容旧工具或保留程序化配置时可以继续保留；重点是停止直接调用它完成安装、开发安装和打包。

version 应该写在 project 还是 dynamic？

能稳定静态确定就写 [project].version；必须从 Git 或源码计算时才声明 dynamic，并确认构建后端知道如何提供该值。

为什么构建成功但安装后缺少模块？

优先检查包发现规则和 wheel 文件清单，尤其是 src 布局、命名空间包与非 Python 数据文件，而不是先反复重装 setuptools。

迁移的完成标志不是“仓库里出现了一个 pyproject.toml”，而是元数据来源清楚、构建依赖与运行依赖分开、sdist 和 wheel 内容可解释，并且普通安装与 editable 安装都通过同一份检查清单。