怎样通过pyproject.toml现代化标准统一配置Python环境？-Python教程-PHP中文网

pyproject.toml能统一环境配置，但必须严格遵循PEP 621标准：Python版本和运行依赖写在[project]下，dev/test依赖用[project.optional-dependencies]声明，工具配置放[tool.*]下，且[build-system]需匹配构建后端与版本。

怎样通过pyproject.toml现代化标准统一配置python环境？

直接用 pyproject.toml 就能统一环境配置，但前提是别把它当“另一个 requirements.txt”来填依赖——它管的是构建、运行、开发全链路，填错位置或混用工具语义会导致 pip 安装失败、uv run 找不到入口、甚至 CI 里测试跑不起来。

把 Python 版本和基础依赖写进 `[project]` 而不是 `[tool.poetry]`

很多人从 Poetry 迁移过来，习惯性把 python = "^3.10" 写在 [tool.poetry.dependencies] 下，结果用 pip install . 安装时完全不校验 Python 版本，直到运行时报 ModuleNotFoundError 才发现是解释器太老。

[project] 下的 requires-python = ">=3.10" 是 PEP 621 强制字段，pip 和 uv 都会检查，安装前就报错
dependencies 必须写在 [project] 下，不是 [tool.poetry.dependencies] 或 [tool.setuptools] —— 后者只被对应工具读，pip 不认
如果项目同时支持 Poetry 和标准 pip 构建，删掉整个 [tool.poetry] 段，改用纯 PEP 621 语法，否则 Poetry 会覆盖 [project] 的依赖解析逻辑

区分 `dev` 和 `test` 依赖要用 `[project.optional-dependencies]`

写成 pip install -r requirements-dev.txt 是倒退。现代方式是声明式分组，然后按需激活：

必须用 [project.optional-dependencies]，不是 [tool.black] 或自定义 key；否则 pip install ".[dev]" 会静默忽略
常见错误：把 pytest 放进 dev 组却没在 CI 中加 [test] 组，导致 pip install ".[test]" 报错找不到 pytest
推荐最小分组：dev = ["black", "ruff"]、test = ["pytest", "pytest-cov"]、docs = ["sphinx"]，避免混合职责

工具配置（如 `black`、`ruff`）必须放在 `[tool.]` 下且路径正确

black 不读 [project] 下的配置，ruff 也不认 [tool.black] —— 错放位置等于没配。

Python Hardener

通过完整的安全审查、代码整洁重构、健壮的错误处理、正确的日志记录以及完整的文档字符串覆盖，强化 Python 脚本。

下载

[tool.black] 控制格式化行为，line-length = 88 有效；但写成 [tool.ruff.black] 或 [black] 就完全失效
[tool.ruff.lint] 和 [tool.ruff.format] 是两个独立表，select = ["E"] 在 lint 下才起作用，format 下写无效
用 uv run black . 时，uv 会自动识别 [tool.black]，但前提是 black 已声明在 [project.optional-dependencies.dev] 里，否则命令根本不存在

`[build-system]` 的 `requires` 版本必须与实际构建兼容

写 requires = ["setuptools>=42"] 看似安全，但在 2026 年已过时：新版 setuptools 默认禁用旧插件机制，会导致 python -m build 报 ImportError: cannot import name 'find_packages'。

当前稳定组合是：requires = ["setuptools>=61.0", "wheel"] 或 requires = ["hatchling"]（更轻量）
build-backend 必须匹配 requires 里的包：选 setuptools.build_meta 就不能漏掉 setuptools；选 hatchling.build 就得把 hatchling 加进 requires
CI 中如果用 pip install --upgrade pip，可能意外升级到不兼容的 setuptools，建议显式固定：pip install "setuptools>=61.0,

最容易被忽略的其实是 requires-python 和 optional-dependencies 的联动：当你在 GitHub Actions 里用 ubuntu-22.04 默认 Python 3.10，但本地用 3.12 开发，仅靠 pyenv 切换版本不够——pip install ".[dev]" 会在 CI 里跳过所有 platform_system == 'Darwin' 的依赖，而你根本不会意识到它们没装上。