[project] 是 Python 包构建与依赖管理的事实入口，现代构建工具（如 pdm、hatch、pip wheel）严格依赖 PEP 621 规范的 [project] 表读取元数据；缺失或格式错误将导致构建失败、IDE 依赖推断失效及 PyPI 上传报错。
pyproject.toml 里写 [project] 不是“可选优化”，而是当前 Python 包发布和依赖管理的事实入口。不按 PEP 621 规范配置，pdm build、hatch build、pip wheel（配合现代后端）会直接报错或忽略你写的 setup.py。
PEP 621 是构建工具读取元数据的唯一可信源
现代构建后端（如 pdm-backend、hatchling、flit-core）默认只解析 pyproject.toml 中的 [project] 表，完全跳过 setup.py。哪怕你保留了 setup.py，只要它没被显式声明为构建后端（通过 [build-system] 指定），它就只是个普通 Python 文件。
- 错误现象：
ERROR: No project name specified或AttributeError: 'ProjectBuilder' object has no attribute 'metadata'，本质是构建器根本没找到[project].name - 关键点：
[build-system]中的requires和build-backend必须匹配——比如用pdm-backend，就得确保pyproject.toml里有完整的[project]字段，否则构建失败 - 兼容性影响：旧版
setuptools（setup.py 元数据路径
依赖声明必须放在 [project].dependencies 而不是 requirements.txt
requirements.txt 是运行时安装指令，不是项目元数据。PEP 621 要求所有直接依赖必须声明在 [project].dependencies，否则 pdm install 或 pip install . 无法正确解析依赖树。
- 常见错误：把
requests==2.31.0写进requirements.txt，却没同步到[project].dependencies→ 安装本地包时缺失依赖 - 版本格式差异：
[project].dependencies只接受 PEP 508 格式（如"requests>=2.31.0"），不支持-r requirements.txt或-c constraints.txt这类 pip 特有语法 - 可选依赖必须用
[project.optional-dependencies]，例如dev = ["pytest", "black"]；不能靠extras_require在setup.py里定义
requires-python 和 license 字段直接影响 PyPI 展示与安装拦截
PyPI 会直接读取 [project].requires-python 和 [project].license 渲染页面，并在 pip install 时做环境校验。填错会导致用户安装失败或合规风险。
-
requires-python = ">=3.9"错写成"3.9"（缺>=）→pip无法解析，报Invalid specifier -
license推荐用{ text = "MIT" }或{ file = "LICENSE" }；若用字符串如license = "MIT"，部分工具（如twine check）会警告非标准格式 -
readme = "README.md"必须存在且路径准确，否则 PyPI 上传时提示HTTPError: 400 Client Error: README content is invalid
IDE 和工具链依赖 PEP 621 做自动补全与静态检查
VS Code 的 Pylance、PyCharm 的新版本、以及 pyright 都会从 [project] 提取 requires-python 和 dependencies 来推断类型提示环境和未解析导入。手写 setup.py 会让这些功能失效。
立即学习“Python免费学习笔记（深入）”；
- 典型表现：IDE 显示
import requests为 unresolved reference，即使pip install requests已执行 - 原因：IDE 依赖
pyproject.toml中的[project].dependencies构建虚拟环境依赖图，而非系统级site-packages - 调试建议：运行
pdm show或hatch env show查看实际解析出的依赖列表，比手动翻venv更可靠
pyproject.toml 就算合规」——字段名拼错、嵌套结构漏括号、TOML 注释干扰解析、或者混用旧式 setup.py 逻辑，都会让工具链静默失效。最稳妥的做法是：删掉 setup.py，用 pdm init 或 hatch new 初始化，再逐项填满 [project]。 
