在Python项目里，测试阶段往往需要用pytest、coverage、mock这类工具，它们不应该出现在生产依赖中。通过pyproject.toml，我们可以用标准方式声明测试依赖，并结合构建后端完成环境隔离。
为什么用pyproject.toml管理测试依赖
过去很多人把测试包写进单独的requirements-test.txt，但这样缺乏统一标准，也难与打包工具联动。pyproject.toml被PEP 518和PEP 621采纳，能在一个文件里描述构建系统、项目元数据和可选依赖组。
核心优势
- 依赖分类清晰，测试包作为optional-dependencies的一部分
- 配合pip可直接安装指定依赖组
- 被poetry、setuptools、hatch等工具原生支持
基础配置示例
下面以setuptools为例，展示如何在pyproject.toml中声明测试依赖：
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "demo_app"
version = "0.1.0"
dependencies = ["requests>=2.28.0"]
[project.optional-dependencies]
test = [
"pytest>=7.0",
"pytest-cov>=4.0",
"mock>=5.0"
]
安装测试依赖
配置好后，使用以下命令即可只安装测试相关包：
pip install -e ".[test]"
结合pytest配置
我们还能在pyproject.toml里直接写pytest的设置，避免再维护pytest.ini：
[tool.pytest.ini_options] testpaths = ["tests"] addopts = "-q --cov=demo_app"
多环境依赖管理建议
如果项目同时有lint和docs需求，可以拆成多个可选组：
| 依赖组 | 用途 | 示例包 |
|---|---|---|
| test | 运行单元测试 | pytest, pytest-cov |
| lint | 代码检查 | flake8, black |
| docs | 文档生成 | sphinx |
使用poetry的场景
若采用poetry，它用[tool.poetry.group.test.dependencies]结构，逻辑类似但命令变为poetry install --with test。
常见误区
- 把测试包放进主dependencies，导致生产镜像变大
- 用
input()函数做交互测试时未mock，造成CI卡住 - 忽略Python版本约束，在toml里写错requires-python
良好的测试依赖管理，是持续集成顺畅运行的前提。
只要把测试依赖收敛到pyproject.toml的optional-dependencies，并配合工具配置，就能让环境可复现、职责更分明。
pyproject.tomlPython测试依赖管理修改时间：2026-07-25 21:27:30