Python 3.12为何推荐使用pyproject.toml？

Python 3.12 并未强制要求使用 pyproject.toml，但其默认集成的 pip 23.1+ 和构建工具链已实质性弃用 setup.py——尤其在可编辑安装（pip install -e .）、打包（python -m build）和 CI/CD 流程中，缺失 pyproject.toml 会直接报错或中断；这源于 PEP 517/621 的规范升级：[build-system] 是构建入口的硬性门槛，[project] 则是元数据的权威来源，二者缺一不可；更关键的是，pyproject.toml 不仅关乎发布，还能统一管理 pytest、mypy、lint 等开发配置，大幅降低多配置文件带来的协作冲突与维护成本——对新老项目而言，迁移不是“要不要做”，而是“何时开始才能避开下一个断点”。

Python 3.12 并不“强制”你用 pyproject.toml，但它默认启用 PEP 621 和 pip 23.1+ 的行为，使得跳过它会直接触发警告甚至构建失败——尤其当你用 pip install -e . 或 python -m build 时。

为什么 pip install -e . 在 3.12 里突然报错？

因为 pip 23.1+（随 Python 3.12 默认安装）已将 pyproject.toml 视为“唯一合法入口”。如果项目根目录下没有 pyproject.toml，而只有 setup.py，pip 会拒绝执行可编辑安装，并抛出错误：

ERROR: File "setup.py" not found. Please use pyproject.toml instead.

这不是 bug，是明确的向后兼容断点：PEP 517 要求构建必须通过 [build-system] 声明后端，而 setup.py 不再被当作标准构建入口。

• 旧项目升级到 3.12 后首次运行 pip install -e . 就可能卡在这里
• setup.py 仍能手动运行（python setup.py develop），但该命令已被 setuptools 标记为 deprecated
• CI/CD 流水线若硬编码了 pip install -e .，没配 pyproject.toml 就会直接中断

[build-system] 和 [project] 必须共存吗？

必须。[build-system] 是硬性要求，[project] 是绝大多数现代后端（setuptools>=68.0、flit、hatch）打包所依赖的元数据源。

• 缺 [build-system] → python -m build 找不到后端，报 No build backend specified
• 缺 [project] → 即使构建成功，生成的 wheel 包也缺少 name、version 等关键字段，PyPI 上传会被拒
• Poetry 2.0+ 是个例外：它支持 [tool.poetry] 替代 [project]，但必须配 [build-system] 才能被 build 工具识别

哪些工具在 3.12 下已不兼容纯 setup.py？

不是所有工具都一刀切，但主流构建和安装链路已实质性弃用：

• python -m build：完全忽略 setup.py，只读 pyproject.toml
• pip wheel . 和 pip install .（非 editable）：仍能 fallback 到 setup.py，但会输出 WARNING，且未来 pip 版本将移除 fallback
• twine check dist/*.whl：检查 wheel 元数据时，若 PKG-INFO 里字段为空（因没 [project]），会报 Missing required field 'Name'
• VS Code Python 插件、PyCharm 新建项目向导：默认只生成 pyproject.toml，不再创建 setup.py

真正容易被忽略的是：即使你不用发布包，只要项目有依赖管理或测试配置（比如 [tool.pytest]），把它们全塞进一个 pyproject.toml 里，就能避免 pytest.ini、mypy.ini、pylintrc 多文件冲突——这点在团队协作中比打包本身更常踩坑。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python 3.12为何推荐使用pyproject.toml？》文章吧，也可关注golang学习网公众号了解相关技术文章。