必须添加pyproject.toml文件，因其是python 3.12+中pip install -e .的强制构建入口，缺失会导致“file 'setup.py' not found”错误；需同时配置[build-system]（硬性要求）和[project]（元数据源），否则构建失败或wheel包不合法。
因为不加 pyproject.toml，Python 3.12+ 环境下 pip install -e . 会直接报错，且主流工具链已默认跳过 setup.py。
pip install -e . 在 3.12+ 报 “File 'setup.py' not found” 怎么办
这不是环境坏了，是 pip 23.1+（随 Python 3.12 默认安装）强制执行 PEP 517：构建必须通过 pyproject.toml 中的 [build-system] 声明后端。它不再把 setup.py 当作合法入口。
- 临时绕过？可以运行
python setup.py develop，但 setuptools 已标记该命令为deprecated - CI/CD 流水线若硬编码了
pip install -e .，没配pyproject.toml就会直接中断 - 哪怕你只做本地开发、不发包，只要用了
pytest、mypy或ruff，把它们配置塞进pyproject.toml就能省掉一堆独立配置文件（pytest.ini、mypy.ini等）
[build-system] 和 [project] 是不是都得写
是的，二者必须共存，但角色不同：
-
[build-system]是硬性要求：告诉pip、build等工具“用什么构建”，缺了会报No build backend specified -
[project]是绝大多数现代后端（setuptools>=68.0、flit、hatch）打包所依赖的元数据源；缺了会导致生成的 wheel 包没有Name、Version字段，上传 PyPI 时被拒 -
poetry2.0+ 是个例外：可用[tool.poetry]替代[project]，但依然必须配[build-system]才能被build工具识别
为什么不能只靠 setup.py 继续混下去
不是不能跑，而是工具链正在系统性弃用它：
-
python -m build：完全忽略setup.py，只读pyproject.toml -
pip wheel .和pip install .（非 editable）：仍会 fallback 到setup.py，但输出 WARNING，并明确提示“未来 pip 版本将移除 fallback” -
twine check dist/*.whl：若 wheel 的PKG-INFO缺关键字段（因没[project]），会报Missing required field 'Name' - VS Code Python 插件、PyCharm 新建项目向导：默认只生成
pyproject.toml，不再创建setup.py
容易被忽略的关键点
很多人以为“我只写脚本、不发包，不用管这个”，但现实是：只要你用 pip install -e . 装本地包（比如开发 CLI 工具或测试库），或者在项目里集成 black、pytest、ruff 等工具，pyproject.toml 就不是可选项——它是当前 Python 工具链默认期待的唯一配置中心。漏掉 [project.optional-dependencies] 或写错 build-backend 字符串（比如少个点、大小写错），都会导致看似正常却静默失败的构建行为。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
