pyproject.toml 可完全替代 setup.py，但必须在 [build-system] 中明确指定 build-backend 和 requires，否则 pip install . 会因缺失构建工具而失败；推荐 build-backend = "setuptools.build_meta" 并声明对应依赖。
pyproject.toml 可以完全替代 setup.py，但必须明确指定构建后端（build-backend），否则 pip install . 会直接失败。
pyproject.toml 必须包含 build-backend 配置
很多项目迁移时只写 [project] 段就以为够了，结果运行 pip install . 报错：ModuleNotFoundError: No module named 'setuptools' 或更模糊的 Failed to build wheel。这是因为 Python 默认找不到构建工具。
- 最常用且兼容性最好的选择是
setuptools：在[build-system]下写build-backend = "setuptools.build_meta" - 若用
hatchling（Hatch 官方构建器），则写build-backend = "hatchling.build"，需确保已安装hatchling -
flit_core.buildapi适用于纯模块、无 C 扩展的项目，但不支持setup.py风格的cmdclass - 不要省略
requires字段——它声明构建时依赖，例如：requires = ["setuptools>=45", "wheel"]
project.name 和 project.version 怎么填才不踩坑
project.name 是 PyPI 上的包名，project.version 是发布版本号，二者都影响安装行为和依赖解析。
-
project.name必须符合 PEP 508 规范：只能含 ASCII 字母、数字、-、_、.，且不能以-或.开头；推荐全小写 + 连字符（如my-awesome-lib） -
project.version不建议硬编码字符串（如"0.1.0"），尤其在 CI/CD 中容易不同步；推荐用dynamic = ["version"]+[[project.dynamic]]块配合外部读取（如从__init__.py或VERSION文件） - 如果用
setuptools-scm，需额外在[tool.setuptools_scm]下配置，且requires中加入"setuptools-scm[toml]>=6.2"
entry-points 和 dependencies 的写法差异
相比 setup.py 的 entry_points 字典或字符串，pyproject.toml 使用表结构，语法更严格，缩进错误会导致解析失败。
立即学习“Python免费学习笔记（深入）”；
-
[project.entry-points."console_scripts"]是标准写法，注意引号包裹键名；值是"name = 'module:attr'格式，比如："mycmd = 'mypkg.cli:main' -
dependencies是列表，每项是 PEP 508 兼容的依赖字符串，如"requests>=2.28.0"；不支持install_requires那种元组写法 - 可选依赖（extras）写在
[project.optional-dependencies]下，键为 extra 名（如"dev"），值为依赖列表；安装时用pip install ".[dev]" - 不要把
python版本约束写进dependencies——应使用requires-python = ">=3.8"独立字段
如何验证 pyproject.toml 是否生效
光靠 pip install . 成功不代表配置完整，有些字段（如 dynamic 版本、entry-points）只在构建 wheel 或安装后才暴露问题。
- 先运行
python -m build --wheel（需安装build），检查是否生成合法.whl文件；再用tar -tzf dist/*.whl | grep -E "(METADATA|entry_points.txt)"查看元数据是否包含预期字段 - 安装后测试命令行入口：
pip install --force-reinstall --no-deps --no-cache-dir .，然后直接运行mycmd（前提是 shell 已刷新 PATH） - 用
pip show mypkg检查Version、Requires、Required-by是否准确；若Version显示UNKNOWN，说明project.version未被正确解析
真正麻烦的是动态版本和构建后端组合——比如 setuptools-scm + hatchling 不兼容，必须统一构建链路。动手前先确认你用的构建后端是否支持你要的功能，比后期调试快得多。
