python pyproject.toml

聊聊Python的build，这玩意儿其实不算新面孔，早在Python打包工具链里就默默存在了很久，只不过近几年才因为更好的规范性和可扩展性被推到台前。简单说，它是Python官方推荐的打包流程前端工具——不是替代setuptools，而是把那些繁琐的配置和构建选择封装成一套更统一的调用方式。

1，它是什么

build这个工具，本质上是PEP 517和PEP 518这两个提案的产物。以前Python打包基本依赖setup.py直接运行，但那种方式把配置、构建和安装逻辑揉在一起，不同项目用的构建后端不一样（比如setuptools、flit、poetry），调用方式也七零八落。build提供了一个标准化的入口：无论项目用哪个后端，只要它符合PEP 517规范，就都能通过python -m build来生成发行包。

你可能会觉得这和直接跑python setup.py sdist bdist_wheel有什么区别？区别在于中间隔了一层抽象。build不关心你的构建后端是什么，它只负责根据pyproject.toml里的声明去调用对应的后端。就像去餐厅吃饭，你不需要知道后厨用的是什么锅，只要告诉服务员你要什么菜就行。

2，他能做什么

build的主要任务就是生成两种常见的分发格式：源码分发包（sdist）和二进制包（wheel）。这个过程中它会做几件具体的事情：

• 读取pyproject.toml的[build-system]部分，确定用哪个构建后端（比如setuptools）
• 在临时干净的虚拟环境中安装构建依赖
• 运行后端提供的build_wheel和build_sdist接口
• 把产出的.tar.gz和.whl文件放到指定目录（默认是dist/）

实际工作中，你经常需要先构建项目再测试或分发。比如团队里有一个项目的依赖比较复杂，build可以确保每次构建都在隔离环境中完成，不会污染当前环境的依赖。这对于CI/CD流水线尤其重要——每次都在干净的沙箱里构建，能避免本地环境遗留的包对产出造成影响。

另外，build在纯源码分发和wheel分发之间也做了很实用的区分。有些项目依赖C扩展，在本地构建wheel可能需要编译器，这时候build可以只生成sdist，让最终用户在自己的平台上编译。而在打包纯Python项目时，直接生成wheel会更快，用户安装起来也方便。

3，怎么使用

使用build其实很简单，基本上是三步走：

先安装它：

pip install build

然后在项目根目录（有pyproject.toml的地方）运行：

python -m build

它会自动在当前目录寻找pyproject.toml，构建完毕后把文件放到dist/目录下。如果只想构建其中一种格式，也可以加参数：

• python -m build --sdist只生成源码包
• python -m build --wheel只生成wheel包

有个经常被忽略的细节：build默认不会生成sdist，如果你同时需要两种格式，直接用不带参数的命令是最保险的。另外，如果项目的构建后端需要安装额外的依赖才能运行，build会自动处理，用户不需要手动去装那些依赖。

还有一个实用技巧：如果你在做持续集成，可以加上--no-isolation参数跳过临时环境，直接在当前环境构建。但建议只在调试时用，正式构建还是要用隔离模式，避免环境差异导致的问题。

4，最佳实践

说说我个人在项目中摸索出来的几个习惯：

第一，pyproject.toml一定要配置好[build-system]部分。很多新手只配置了元数据，却忘了声明构建后端。一个典型的配置长这样：

[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"

这里requires是构建这个项目需要预先安装的依赖，build-backend指定了调用的后端。如果用的是flit或poetry，对应的后端名称会不一样。

第二，尽量在你的持续集成脚本里用build而不是直接调后端的命令。比如在GitHub Actions中：

-name:Build packagerun:|pip install build python -m build --wheel

这样做的好处是，将来如果换了构建后端，只需要改pyproject.toml，构建命令完全不需要动。

第三，做版本发布时，多验证一下构建的产物的质量。比如在构建后，可以立刻把生成的wheel安装到临时环境测试：

pipinstalldist/*.whl# 然后执行一些导入测试python-c"from mypackage import __version__; print(__version__)"

这样能避免发布后才发现漏文件或版本号错误。

第四，如果项目的源码里包含非Python文件（比如数据文件、模板），记得在pyproject.toml里配置好include或使用MANIFEST.in。很多开发者在这上面栽过跟头，构建出来的包少了配置文件。

5，和同类技术对比

把build跟其他打包工具放在一起看，更能体会它的定位差异。

最直接的对比对象是python setup.py系列命令。那套老办法的问题是，它把构建逻辑硬编码在setup.py里，而且只能配合setuptools用。如果你的项目改用poetry管理依赖，setup.py就没什么用了。而build是完全中立的调度器。

跟poetry内置的构建功能（poetry build）相比，poetry主要是依赖管理器附带打包功能，它的构建逻辑是锁死的，只能用自己的后端。而build可以和任何符合PEP 517规范的后端配合，你可以在项目里用poetry管理依赖，但在构建时依然可以用python -m build。

跟flit自带的构建命令（flit build）类似，build更专注于"构建"这个环节本身。很多时候你发现自己用poetry或flit只是为了它的构建功能，其实完全可以只用一个简单的构建后端加build，这样项目依赖更少，也更灵活。

还有一个轻量级的工具叫tqdm的打包方式，不过那更偏向于微服务部署场景了。

实际项目选型的时候，可以这样考虑：如果团队里已经用了poetry来管理依赖和版本号，那么poetry build就已经够用了，没必要额外再加build。如果项目配置简单，用setuptools加上pyproject.toml就能搞定，那build就是最轻量的选择。如果项目比较复杂# # 关于Python的pyproject.toml，聊聊我的理解

前段时间帮一个朋友整理他的Python项目，他还在用setup.py，项目里requirements.txt、setup.cfg、MANIFEST.in各种文件混在一起，看着就头疼。我建议他试试pyproject.toml，他问我这东西到底好在哪。其实这个问题挺有意思的，因为pyproject.toml经历了好几个版本的演变，不同阶段它在项目里的角色也不太一样。

它到底是什么

简单说，pyproject.toml是一个用TOML格式写的配置文件，放在项目根目录，用来告诉Python世界这个项目该怎么构建、怎么打包、需要哪些依赖。TOML这门语言有点像INI，但比INI多了层级结构，读起来很直观——键值对、数组、表，基本就这三板斧。

这个文件最初来自PEP 518（2016年），目的是解决一个长期困扰大家的问题：一个Python项目到底应该用什么工具来构建。以前没有统一标准，有人用setuptools，有人用flit，有人写poetry，每个工具都要自己的配置方式。pyproject.toml的出现，相当于给了大家一个统一的入口，不管底层用哪个构建工具，配置都放在同一个地方。

后来PEP 621又进一步规范了pyproject.toml的格式，让项目元数据（名字、版本、作者这些信息）也有了统一的存放位置。现在最新版的pip、build这些工具，都能直接识别pyproject.toml。

它到底能做什么

说到能力，我觉得可以从三个层面来看。

第一层，也是最基础的，替代setup.py和setup.cfg。虽然写一个简单的setup.py难不到哪里去，但要维护一个包含复杂配置的setup.py，那种感觉就像在写重复代码。我见过一个项目，setup.py里用了一大堆条件判断来处理不同平台的依赖，读起来简直像在读天书。pyproject.toml用声明式的配置方式，把构建工具的配置放进了独立的条目下面，清晰得多。

第二层，管理项目依赖。传统的做法是requirements.txt配上pip freeze，但这种方式的问题是：谁来确定这些依赖是项目本身需要的，还是只是开发过程中临时装的？pyproject.toml支持区分不同场景的依赖——运行需要的、测试需要的、文档需要的、开发工具链需要的。这个类比打包行李：出门住酒店，真正需要的底裤牙刷（运行依赖），和那些看着好玩但可能用不上的东西（可选依赖），放在不同的口袋里，需要的时候才拿出来。

第三层，定义构建后端。这是pyproject.toml最核心的革新之处。以前你要用某个构建工具，得手动装好，然后调用它的命令行。现在只需要在pyproject.toml里声明一下“我用Setuptools作为构建后端”，pip就会自动处理剩下的事情。这就好比你跟外卖平台说“我要吃宫保鸡丁”，平台自己会去联系对应的餐厅、安排配送，你不需要知道厨房里发生了什么。

怎么上手用

实际用起来并不复杂。假设新建一个项目，叫my-tool。在项目根目录创建一个pyproject.toml文件，里面至少要有一个[build-system]条目，指定构建后端。选择用Setuptools的话，可能还需要配套的setup.cfg（或者也能集中到pyproject.toml里）。不过现在越来越多的项目选择用Poetry或者Flit，这两种工具都支持把几乎所有配置写在pyproject.toml里，不需要额外配置文件。

比如说用Poetry创建一个项目：

[build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" [tool.poetry] name = "my-tool" version = "0.1.0" description = "一个简单的示例项目" authors = ["你的名字 <you@example.com>"] [tool.poetry.dependencies] python = "^3.8" requests = "^2.28.0" [tool.poetry.group.dev.dependencies] pytest = "^7.0.0"

这里有几个有意思的地方。requires定义了构建时需要的包，build-backend指定了实际干活的构建后端。[tool.poetry]开头的是Poetry自己的配置空间，因为pyproject.toml也允许不同工具用tool.工具名来定义自己的配置。

运行python -m build或者poetry build就能生成wheel包和sdist包了。如果用Poetry，还能用poetry add requests自动更新pyproject.toml。

一些值得注意的做法

Pyproject.toml虽然灵活，但用得不好也会制造麻烦。有几个经验可以参考。

每个项目最好只用一种构建工具。不要把Poetry和Setuptools的配置混在一起写，容易冲突。选定了就坚持下去，除非有特别好的理由要切换。

注意Python版本的兼容性。如果你的项目需要支持Python 3.6或更老的版本，那么pyproject.toml可能会带来一些限制，因为老版本的pip对它的支持不够完善。不过2023年的现在，大部分用户已经用的是比较新的Python了。

私有包索引需要配置清楚。如果公司内部有PyPI镜像，或者用GitLab的包 registry，需要在pyproject.toml里加上相关的配置。比如Poetry的方式是在[[tool.poetry.source]]里面配置。

依赖版本范围要合理。初学者容易把依赖写死成==1.2.3，导致用户没法升级补丁版本。推荐用>=加<的方式，比如requests>=2.28.0,<3.0.0。这背后的逻辑是，希望用户能用上最新的安全修复，但也不想看到一个不兼容的大版本更新时项目炸掉。

和其他配置方式的对比

最后聊聊pyproject.toml跟其他方案的比较。

vs setup.py + setup.cfg：传统方式。setup.py实际上是一个可执行的Python脚本，意味着你可以在里面写任意的Python代码来做构建相关的判断。这既是优势也是劣势——灵活性高，但容易写出难以维护的配置。pyproject.toml牺牲了这种灵活性，换来了可读性和工具的一致性。对于绝大部分项目来说，收益大于损失。

vs requirements.txt：requirements.txt本质上是一个裸的依赖列表，没有版本控制的粒度，也没有区分场景的能力。pyproject.toml的依赖管理更结构化。但值得注意的是，requirements.txt并没有被取代。很多项目依然会生成一个requirements.txt文件，只是它现在是从pyproject.toml锁定的版本中导出来的，用于部署环境。角色变了，从一个主配置文件变成了一个部署工件。

vs Pipfile / Pipenv：Pipenv是早期试图统一Python依赖管理的尝试，用Pipfile和Pipfile.lock。但它的设计复杂度过高，社区接受度一直不太高。pyproject.toml的设计思路更轻量，更接近符合直觉的工作流。

vs setup.py的区别：setup.py是可以带逻辑的。比如根据操作系统不同选择不同的依赖，这在pyproject.toml里需要用构建工具提供的机制来实现（比如Setuptools的extras_require+ 平台标记）。一般来说，现在不太建议在构建流程里写太复杂的逻辑，这样做的好处是构建的可复制性更强。

说到底，pyproject.toml不是一个银弹，它解决的是Python项目长期以来在构建和依赖管理上缺少统一标准的问题。就像每个人家里都会有一个固定的地方放钥匙和钱包——pyproject.toml给了Python项目一个约定俗成的说明书的位置。，比如有多个构建阶段或前后端混编，那build的隔离构建环境能帮你省去很多脏活累活。

说到底，build解决的不是"能不能构建"的问题，而是"怎么构建得更好"的问题。它让构建过程和特定工具解耦，这在多人协作和维护长期项目时，价值会越来越明显。