《Python 项目配置的“大一统”：深入理解 pyproject.toml 的力量》

《Python 项目配置的“大一统”：深入理解 pyproject.toml 的力量》

“一个文件，统一构建、依赖与配置，Python 项目终于有了自己的‘中枢神经’。”

在过去的十几年里，Python 项目的构建与管理一直处于“多文件共治”的状态：setup.py 负责打包，requirements.txt 管理依赖，setup.cfg 做静态配置，MANIFEST.in 控制文件包含……每个文件都有自己的职责，却也带来了混乱与重复。

直到 PEP 518 的出现，Python 社区终于迎来了一个统一的解决方案：pyproject.toml。

本文将带你全面理解 pyproject.toml 的设计初衷、核心结构与实战应用，帮助你在项目中优雅地管理构建工具、依赖配置与元数据，真正实现 Python 项目的现代化管理。

---

一、为什么需要 pyproject.toml？

背景回顾

在传统 Python 项目中，开发者常常需要维护多个配置文件：

• setup.py：定义包的元数据与构建逻辑
• requirements.txt：列出依赖包
• setup.cfg：静态配置替代 setup.py 的部分逻辑
• MANIFEST.in：控制打包时包含的文件

这种方式虽然灵活，但也带来了：

• 配置分散，难以维护
• 构建工具耦合，难以替换
• 缺乏标准化，工具兼容性差

PEP 518 的诞生

为了解决这些问题，PEP 518 提出了一个新标准：使用 pyproject.toml 作为项目的统一配置入口。它的目标是：

• 统一构建工具配置
• 支持多种构建后端（如 setuptools、poetry、flit）
• 简化项目结构与依赖管理

---

二、pyproject.toml 的核心结构

一个典型的 pyproject.toml 文件如下：

[build-system]
requires = ["setuptools>=42", "wheel"]
build