pip install -e . 在 Python 3.12 中报错，是因为 pip 23.1+ 默认要求 pyproject.toml 作为唯一构建入口，若缺失则拒绝可编辑安装并提示“File 'setup.py' not found”，这是 PEP 517/621 的强制性变更，非 bug。
Python 3.12 并不“强制”你用 pyproject.toml，但它默认启用 PEP 621 和 pip 23.1+ 的行为，使得跳过它会直接触发警告甚至构建失败——尤其当你用 pip install -e . 或 python -m build 时。
为什么 pip install -e . 在 3.12 里突然报错？
因为 pip 23.1+（随 Python 3.12 默认安装）已将 pyproject.toml 视为“唯一合法入口”。如果项目根目录下没有 pyproject.toml，而只有 setup.py，pip 会拒绝执行可编辑安装，并抛出错误：
ERROR: File "setup.py" not found. Please use pyproject.toml instead.
这不是 bug，是明确的向后兼容断点：PEP 517 要求构建必须通过 [build-system] 声明后端，而 setup.py 不再被当作标准构建入口。
- 旧项目升级到 3.12 后首次运行
pip install -e .就可能卡在这里 -
setup.py仍能手动运行（python setup.py develop），但该命令已被 setuptools 标记为 deprecated - CI/CD 流水线若硬编码了
pip install -e .，没配pyproject.toml就会直接中断
[build-system] 和 [project] 必须共存吗？
必须。[build-system] 是硬性要求，[project] 是绝大多数现代后端（setuptools>=68.0、flit、hatch）打包所依赖的元数据源。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
- 缺
[build-system]→python -m build找不到后端，报No build backend specified - 缺
[project]→ 即使构建成功，生成的 wheel 包也缺少name、version等关键字段，PyPI 上传会被拒 - Poetry 2.0+ 是个例外：它支持
[tool.poetry]替代[project]，但必须配[build-system]才能被build工具识别
哪些工具在 3.12 下已不兼容纯 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
真正容易被忽略的是：即使你不用发布包，只要项目有依赖管理或测试配置（比如 [tool.pytest]），把它们全塞进一个 pyproject.toml 里，就能避免 pytest.ini、mypy.ini、pylintrc 多文件冲突——这点在团队协作中比打包本身更常踩坑。
