pyproject.toml 是什么
pyproject.toml 按 PEP 518 与 PEP 621 承载构建配置与项目元数据，同时也是 Python 工具配置的集中地：Black、Ruff、mypy、pytest、isort 都能写进各自的 [tool.*] 段，替掉 setup.cfg、.flake8、tox.ini 里散落的一份份配置。
基本信息
| PEP 518 | build-system 段声明构建后端与构建依赖 |
|---|---|
| PEP 621 | project 段承载名称、版本、依赖等元数据 |
| 工具段 | [tool.black] [tool.ruff] [tool.mypy] 等 |
| 收益 | 新成员在一个文件里看完所有质量工具配置 |
典型使用场景
- 新项目初始化：从第一天就用 pyproject 做配置入口
- 存量项目迁移：把散落的工具配置逐段搬进来，再删旧文件
- 依赖与元数据统一：安装依赖不再依赖 setup.py
- 团队工具版本对齐：依赖清单与配置同处一个仓库
- 多工具共享行宽：Black、Ruff、isort 的 line-length 保持一致
迁移时的检查点
- 目标工具是否支持从 pyproject 读取配置
- 旧配置文件是否还有 CI 或脚本在引用
- 行宽、目标 Python 版本等公共项是否一致
- 格式化基线与检查规则是否在同一次改动里对齐
配置片段
配置片段
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "orders"
version = "1.4.0"
requires-python = ">=3.11"
[tool.black]
line-length = 88
[tool.ruff]
line-length = 88
[tool.mypy]
strict = true三类段落的分工
| 段落 | 作用 | 常见内容 |
|---|---|---|
| build-system | 声明构建后端 | 构建依赖与后端入口 |
| project | 项目元数据 | 名称、版本、依赖、入口脚本 |
| tool.* | 各工具自己的配置 | 行宽、目标版本、规则开关 |
配置集中之后工具版本仍要锁定：依赖清单里固定版本，避免本地与 CI 行为漂移。
迁移时先确认工具版本：不同版本的配置键名与默认值可能发生变化，把迁移与升级混在一次改动里会很难定位问题出在哪一段。
让多个工具共享同一个行宽取值，仓库里就不会出现格式化器与检查器互相打架的局面。
新老配置并存：setup.cfg、tox.ini 与 pyproject 同时在仓库里时，实际生效的可能是旧文件。