Python：pyproject.toml 配置归一：Ruff、mypy、pytest 全塞进一个文件，零散配置清零

一、问题的起点：Python 配置为何会碎片化

任何一个维护过三年以上 Python 仓库的工程师，大概率都见过这样的目录结构：根目录下散落着 .flake8、mypy.ini、pytest.ini、.coveragerc、tox.ini、setup.cfg、setup.py、requirements-dev.txt。每个文件单独看都合理，合在一起却形成了一种“配置黑洞”——新人入职第一周往往花大量时间搞清楚“哪个工具读哪个文件”。

这种碎片化并非设计失误，而是历史演进的副产品。Python 生态的工具大多诞生于不同的年代，各自选择了当时最方便的配置载体。flake8 沿用了 configparser 的 INI 风格；mypy 早期受 mypy 自身历史影响使用 INI；pytest 早期也依赖 INI；打包工具则经历了 setup.py → setup.cfg → pyproject.toml 的三级跳。本文评述认为，配置碎片化的本质是“工具自治”与“项目一致性”之间的张力：每个工具都想拥有最贴合自身语义的配置格式，但项目维护者需要的是单一事实来源（Single Source of Truth）。

1.1 碎片化的三类成本

第一类是认知成本。开发者需要记住“哪个工具读哪个文件”，这在跨项目切换时尤其痛苦。第二类是语义漂移成本：同一个规则（比如行长度）在不同文件里被重复声明，一旦某处忘记同步，就会出现“flake8 认为 88 列合规、black 按 100 列格式化”的冲突。第三类是工具链成本：CI 脚本、pre-commit、编辑器插件都需要分别适配多个配置文件路径。

配置碎片化最隐蔽的代价，是它让“项目规范”变成了“工具规范的并集”，而不是“团队共识的投影”。当规则来源分散，规则本身就不再可审计。

1.2 一个典型仓库的配置清单

上表基于对 PyPA 官方文档与各工具官方文档的整理（来源：PyPA Packaging Guide, 2024；Ruff Docs, 2025；mypy Docs, 2025）。可以看到，绝大多数工具的配置都可以收敛到 pyproject.toml，这也是本文讨论的工程基础。

二、规范演进：pyproject.toml 的标准化之路

要理解配置收敛的可行性，必须先理解 pyproject.toml 的规范地位。它不是一个“随便放配置的 TOML 文件”，而是由一系列 PEP 逐步定义的标准载体。

2.1 PEP 518：构建系统声明的起点

PEP 518（2016）首次提出用 pyproject.toml 声明构建依赖，核心是 [build-system] 表，包含 requires 与 build-backend。它解决的是“构建项目本身需要哪些工具”的问题。本文评述认为，PEP 518 的真正贡献不是引入 TOML，而是确立了“构建依赖与运行时依赖分离”的思想，这为后续工具配置的集中化埋下伏笔。

2.2 PEP 517 与 PEP 621：构建后端与项目元数据

PEP 517 定义了构建后端的接口标准，使得 setuptools、hatchling、flit、pdm-backend、poetry-core 等可以并存。PEP 621（2020）则定义了 [project] 表，把 name、version、dependencies、authors 等元数据标准化。这意味着 setup.py 中的大部分声明式内容可以迁出。

2.3 工具配置的“事实标准”

PEP 518/621 并未规定 [tool.*] 表的语义，但社区迅速形成了约定：每个工具在 [tool.<name>] 下放置自己的配置。这一约定没有强制力，却因为“零成本、零依赖”被广泛采纳。截至 2025 年，主流工具几乎都支持从 pyproject.toml 读取配置。

三、工具适配现状全景表

下表汇总了截至 2025 年主流 Python 开发工具对 pyproject.toml 的支持情况。数据来源为各工具官方文档与 GitHub 仓库 README（检索时间：2025 年）。

本文评述认为，这张表揭示了一个趋势：新工具默认以 pyproject.toml 为第一配置源，老工具通过兼容层支持。Ruff 是典型的新工具代表，它从设计之初就把 pyproject.toml 作为首选，甚至不提供独立的 INI 格式。这种“新工具倒逼老工具”的格局，是配置收敛能够落地的外部条件。

四、Ruff：从替代 flake8 到统一 lint/format

Ruff 由 Astral 团队用 Rust 编写，定位是“极快的 Python linter 与 formatter”。它兼容 flake8、isort、pyupgrade、pydocstyle 等大量规则集，并自带格式化能力。对配置收敛而言，Ruff 的意义在于：它把原本分散在 flake8、isort、pyupgrade、pydocstyle 等多个工具的配置，合并到一个 [tool.ruff] 表里。

4.1 基础配置结构

[tool.ruff]
line-length = 100
target-version = "py311"
src = ["src", "tests"]

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

上面这段配置替代了传统仓库中的 .flake8、.isort.cfg、.pyupgrade 等多个文件。本文评述认为，Ruff 的 select/ignore 模型比 flake8 的 extend-select 更直观，但迁移时需要注意规则码前缀的对应关系，比如 flake8-bugbear 的 B 前缀在 Ruff 中保持一致，而 pydocstyle 的 D 前缀需要显式启用。

4.2 与 black 的关系

Ruff format 在 2024 年进入稳定阶段，官方声称与 black 的兼容度达到 99% 以上（来源：Ruff 官方博客《Ruff Formatter Stable》，2024）。实践中，团队可以选择“Ruff lint + black format”或“Ruff lint + Ruff format”。前者迁移风险低，后者配置更集中。笔者认为，如果团队已经决定收敛配置，直接采用 Ruff format 更符合“单一工具、单一配置”的目标，但需要在 CI 中锁定版本，避免格式化规则随版本变化。

4.3 性能与配置的权衡

Ruff 官方基准显示，在大型代码库上其速度比 flake8 快 10–100 倍（来源：Ruff 官方文档 Performance 章节，2025）。但速度优势并不意味着可以随意扩大规则集。规则越多，误报概率越高，团队需要维护的 ignore 列表越长。本文评述认为，配置收敛的目标不是“把所有规则打开”，而是“让规则来源单一、可审计”。

五、mypy 与类型检查的配置收敛

mypy 是 Python 静态类型检查的事实标准。它早期使用 mypy.ini，后来支持 setup.cfg，最终在 0.900+ 版本完整支持 pyproject.toml 的 [tool.mypy] 表。

5.1 核心配置项

[tool.mypy]
python_version = "3.11"
strict = true
warn_unused_configs = true
warn_redundant_casts = true
warn_unused_ignores = true
disallow_untyped_defs = true
disallow_any_generics = true
no_implicit_optional = true
show_error_codes = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

strict = true 是 mypy 提供的“严格模式开关”，它会一次性启用多项检查。本文评述认为，严格模式适合新项目，但老项目直接开启会产生海量报错。更务实的路径是：先开启 warn_unused_ignores 与 show_error_codes，再按模块逐步收紧，利用 [[tool.mypy.overrides]] 做差异化配置。

5.2 与 Ruff 的职责边界

Ruff 也提供部分类型相关规则（如 ANN 前缀的注解检查），但它不做类型推断。mypy 负责类型正确性，Ruff 负责风格与注解完整性。两者配置都放在 pyproject.toml 后，团队可以在一个文件里看到“风格规则”与“类型规则”的全貌，这降低了规则冲突的概率。

5.3 增量检查与缓存

mypy 支持 --cache-dir 与增量检查。在 pyproject.toml 中可以配置 cache_dir，配合 CI 缓存可以显著缩短检查时间。需要注意的是，mypy 缓存与 Python 版本、mypy 版本强相关，CI 中应把版本号纳入缓存 key。

六、pytest 与 coverage 的集中治理

pytest 的配置键是 [tool.pytest.ini_options]，这个略显别扭的名字是历史遗留：pytest 内部仍以 INI 语义解析，只是把载体换成了 TOML。理解这一点有助于避免配置迁移时的格式错误。

6.1 pytest 配置示例

[tool.pytest.ini_options]
minversion = "7.0"
addopts = "-ra -q --strict-markers --strict-config"
testpaths = ["tests"]
pythonpath = ["src"]
markers = [
    "slow: marks tests as slow",
    "integration: marks integration tests",
]
filterwarnings = [
    "error",
    "ignore::DeprecationWarning:third_party.*",
]

--strict-markers 与 --strict-config 是两个值得默认开启的选项：前者防止拼错 marker 名称，后者防止配置键拼写错误被静默忽略。本文评述认为，这两个选项的价值在配置收敛后更加突出——当所有配置集中在一个文件时，一个拼写错误可能影响多个工具，严格模式能尽早暴露问题。

6.2 coverage 配置

[tool.coverage.run]
branch = true
source = ["src"]
omit = ["*/tests/*", "*/migrations/*"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
]
fail_under = 85
show_missing = true

fail_under 设置覆盖率下限，配合 CI 可以防止覆盖率回退。需要注意的是，fail_under 的阈值应基于项目实际水平设定，盲目追求 100% 会诱导开发者写“为覆盖而覆盖”的测试。笔者认为，覆盖率是手段而非目的，配置收敛的意义在于让这个阈值有唯一来源，而不是散落在 CI 脚本里。

6.3 与 pytest-cov 的配合

pytest-cov 会读取 [tool.coverage.*] 配置。典型命令是 pytest --cov=src --cov-report=term-missing。由于 coverage 配置已在 pyproject.toml 中，命令行只需指定 --cov 的目标包，其余细节由配置文件决定，这减少了 CI 脚本的复杂度。

七、迁移实操：从零散文件到单文件

本节给出一个可复用的迁移路径。假设一个典型仓库包含 .flake8、mypy.ini、pytest.ini、.coveragerc、setup.cfg。

7.1 迁移步骤

1. 盘点现状：列出所有配置文件及其消费者，确认哪些工具支持 pyproject.toml。
2. 建立基线：在迁移前运行一次完整检查，记录当前报错数量与覆盖率，作为回归对照。
3. 逐工具迁移：先迁移 mypy（配置项少），再迁移 pytest，最后迁移 flake8 → Ruff（规则映射最复杂）。
4. 删除旧文件：每迁移一个工具，删除对应旧配置文件，避免“双源”导致的行为不一致。
5. 验证一致性：对比迁移前后的检查结果，确保没有规则被意外启用或禁用。

7.2 完整示例

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "example-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["httpx>=0.27"]

[project.optional-dependencies]
dev = ["ruff", "mypy", "pytest", "pytest-cov"]

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]

[tool.mypy]
python_version = "3.10"
strict = true

[tool.pytest.ini_options]
addopts = "-ra -q --strict-markers"
testpaths = ["tests"]

[tool.coverage.run]
branch = true
source = ["src"]

[tool.coverage.report]
fail_under = 85

这份配置覆盖了构建、依赖、lint、类型、测试、覆盖率六个维度，全部集中在一个文件。本文评述认为，它的价值不仅在于“文件少”，更在于所有工具共享同一份项目上下文：requires-python 与 target-version、python_version 之间的对应关系一目了然，减少了版本不一致的风险。

7.3 常见坑

• TOML 语法陷阱：数组与内联表的写法容易出错，建议用 tomllib 或 taplo 校验。
• 键名大小写：TOML 键名区分大小写，[tool.pytest.ini_options] 不能写成 [tool.pytest.iniOptions]。
• 工具版本：老版本工具可能不支持某些键，迁移前应升级到支持 pyproject.toml 的最低版本。
• 优先级问题：部分工具同时存在多个配置源时，优先级规则不同，迁移期间应确保旧文件已删除。

八、单体仓库与多包场景的进阶策略

单体仓库（monorepo）中，多个子包可能各有 pyproject.toml。此时配置收敛面临新问题：是每个子包独立配置，还是根目录统一配置？

8.1 两种模式

模式 A：根配置 + 子包继承。根目录放共享配置，子包通过 extend 或工具自身的继承机制覆盖。Ruff 支持 extend 键，mypy 支持 [[tool.mypy.overrides]]，pytest 支持 rootdir 机制。

模式 B：各包自治。每个子包独立配置，适合包之间差异大、团队边界清晰的场景。代价是配置重复，规则容易漂移。

本文评述认为，模式 A 更符合“配置收敛”的主线，但需要工具支持继承。Ruff 的 extend 设计得比较干净：子包配置可以 extend = "../pyproject.toml"，只覆盖差异项。mypy 的继承能力较弱，实践中更多依赖 CI 脚本统一指定配置文件。

8.2 工作区工具的配合

uv、PDM、Hatch 等工作区工具支持在根 pyproject.toml 中声明 workspace 成员。以 uv 为例，[tool.uv.workspace] 可以声明成员包，配合 uv run 可以在整个工作区执行命令。这进一步强化了“根配置为单一事实来源”的模式。

九、CI、编辑器与 AI 上下文的联动

配置收敛的收益会在 CI 与编辑器环节被放大。

9.1 CI 缓存策略

由于所有工具配置都在 pyproject.toml，CI 缓存 key 可以统一包含该文件的哈希值。一旦配置变化，缓存自动失效，避免“配置改了但缓存没更新”的诡异问题。Ruff、mypy 各自的缓存目录也应纳入缓存范围。

9.2 编辑器联动

VS Code 的 Ruff 扩展、Pylance、mypy 扩展都会自动读取 pyproject.toml。配置收敛后，编辑器与 CI 使用同一份规则，减少了“本地通过、CI 失败”的摩擦。本文评述认为，这是配置收敛最直接的开发者体验收益。

9.3 AI 辅助编码的上下文价值

2024 年以来，AI 编码助手（如 GitHub Copilot、Cursor）越来越依赖项目配置文件来推断代码风格。当规则分散在多个文件时，AI 需要读取多个来源；当规则集中在 pyproject.toml 时，AI 只需读取一个文件即可获得完整上下文。笔者认为，这将成为配置收敛的新驱动力：机器可读的单一配置源，是 AI 生成符合项目规范代码的前提。

十、前沿预判与结论

从 2016 年 PEP 518 到 2025 年，pyproject.toml 用近十年时间完成了从“构建声明”到“项目中枢”的转变。本文评述认为，未来三年会出现三个趋势。

趋势一：工具配置的 schema 化。目前 [tool.*] 表的键名由各工具自行定义，缺乏统一 schema。社区已有讨论为常用工具建立 JSON Schema，用于编辑器补全与校验。这会让配置收敛更安全。

趋势二：Rust 系工具的进一步整合。Ruff 已经整合 lint 与 format，uv 整合了包管理与虚拟环境。未来可能出现“一个工具、一个配置表”的极简形态，进一步压缩配置文件数量。

趋势三：AI 驱动的配置生成与迁移。把旧配置文件迁移到 pyproject.toml 是一个规则明确的转换任务，适合由 AI 辅助完成。但迁移结果仍需人工审计，尤其是规则映射部分。

回到本文主线：配置收敛不是目的，而是手段。它的真正价值在于让项目规范有唯一、可审计、机器可读的来源。当 Ruff、mypy、pytest 的配置都进入 pyproject.toml，团队获得的不仅是“少几个文件”，而是一份可以被 CI、编辑器、AI 共同消费的项目契约。这份契约的清晰程度，直接决定了协作效率的上限。

主要参考文献