pyproject.toml存在时setup.cfg会被完全忽略，现代工具（如pip≥21.3）跳过setup.cfg和setup.py，仅以pyproject.toml为唯一权威配置源，pep 621明确要求其为唯一配置入口。
pyproject.toml 存在时 setup.cfg 会被完全忽略
只要项目根目录下有 pyproject.toml，现代构建工具（如 pip ≥21.3、setuptools ≥61.0）会**跳过 setup.cfg 和 setup.py 的读取**，哪怕它们还留在项目里。这不是“优先级高低”问题，而是明确的弃用行为——PEP 621 规定 pyproject.toml 是唯一权威配置源。
常见错误现象：pip install -e . 报错说找不到 install_requires，但你明明在 setup.cfg 里写了；或者 build 生成的包没包含数据文件，而 MANIFEST.in 也没生效——根本原因就是工具压根没看那些文件。
- 检查是否真被忽略：运行
python -m build --debug，输出里若出现Using PEP 517 backend且无 setup.cfg 加载日志，说明已切换到 TOML 模式 - 不要保留旧文件“以防万一”：残留的
setup.cfg容易误导协作者或 CI 脚本，误以为它还在起作用 - 迁移不是“复制粘贴”：
setup.cfg中的[metadata]对应[project]，但[options.packages.find]需转为[project.dynamic]或显式声明packages = ["my_pkg"]
setup.cfg 与 pyproject.toml 同时存在时的典型报错
最常遇到的是 PREPARING METADATA (PYPROJECT.TOML) ERROR，尤其在使用旧版 setuptools 或未声明构建后端时。错误本质是：工具尝试解析 pyproject.toml，却发现缺少 [build-system] 或 [project] 必需字段，于是回退失败，又不读 setup.cfg，最终卡死。
- 必须显式声明构建系统：哪怕只用 setuptools，也要在
pyproject.toml里写清[build-system]块，否则 pip 无法判断该用哪个后端 -
[project]至少要有name和version：这两个是 PEP 621 强制字段，漏掉就会触发元数据准备失败 - 别依赖隐式 fallback：某些老版本 pip 会尝试 fallback 到 setup.py，但 2026 年主流环境（包括 PyCharm 2026.1、tox 4.x、hatch）已彻底移除该逻辑
如何安全迁移 setup.cfg 到 pyproject.toml
直接删掉 setup.cfg 不行，得先补全 pyproject.toml 的等效配置，再验证行为一致。重点不是字段一一对应，而是确保打包、安装、依赖解析结果不变。
-
[metadata]→[project]：把name、version、description、author等平移过去；long_description改用readme = "README.md" -
[options]中的install_requires→[project.dependencies]：注意格式差异，TOML 里是数组，不是 INI 的换行字符串 -
[options.packages.find]→[project]下的dynamic = ["packages"]或直接写packages = ["src/my_pkg"]；若用find = { where = ["src"] }，需确认构建后端支持（setuptools ≥64.0） - MANIFEST.in 功能 →
[project.include-package-data]或[tool.setuptools.package-data]：前者控制是否包含非 Python 文件，后者指定具体 glob 模式
CI/CD 和 IDE 中容易被忽略的兼容点
PyCharm 2026.1、VS Code Python 插件、GitHub Actions 的 python-setup-action 都会自动识别 pyproject.toml 并据此配置解释器和依赖，但前提是文件结构合规。一个看似微小的缩进或类型错误，会导致整个环境初始化失败。
- 检查 TOML 语法：用
tomlkit或在线 toml-lint 工具验证，[[tool.black]]错写成[tool.black]会导致 black 不生效 - 虚拟环境创建时默认不读 setup.cfg：即使你用
python -m venv创建环境，后续pip install -e .也只认pyproject.toml，旧配置毫无意义 - 私有 PyPI 场景下，
requires-python字段必须显式声明：否则 pip 可能因无法判断兼容性而跳过你的包，尤其当服务器启用了严格元数据校验时
pyproject.toml 存在，所有其他打包配置文件都只是磁盘垃圾。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
