pyproject.toml 不能仅写 [build-system]，因为工具链需实际消费字段：pip install -e . 需 [project]，poetry 忽略它，[build-system.requires] 必须匹配真实构建工具，动态 version 易被缓存坑，setup.py 虽弃用但 CI 可能仍依赖。
为什么 pyproject.toml 不能只写 [build-system] 就完事
因为 Python 的“配置即代码”不是把配置文件写全就自动生效，而是依赖工具链对字段的实际消费。比如 setuptools 会读 [project]，但 poetry 默认忽略它；pip install -e . 只认 [build-system] + [project]，而 pipx 安装时还会检查 [project.scripts] 是否存在。
常见错误现象：pip install -e . 成功但 import mypkg 报 ModuleNotFoundError；或者 python -m build 失败，提示 Unknown distribution option: 'entry_points'。
- 必须确保
[build-system.requires]包含真正用于构建的工具，例如["setuptools>=61.0", "wheel"]，而不是抄别人项目里的["poetry-core"]却没装 poetry -
[project]下的name和version必须是字符串，不能是动态表达式（如"0.1.0.dev"+open("VERSION").read()），否则pip解析失败 - 如果用
src/目录结构，得加[project.paths]或在[tool.setuptools]里配package-dir = {"" = "src"}，否则打包时找不到模块
setup.py 已弃用，但删掉它可能让 CI 崩溃
PEP 621 明确推荐用 pyproject.toml 替代 setup.py，但很多 CI 流水线、Docker 构建脚本或内部工具仍硬编码调用 python setup.py sdist。直接删掉 setup.py 不是“干净”，而是制造隐性故障。
使用场景：你刚迁移到 pyproject.toml，本地 pip install -e . 没问题，但 Jenkins 上跑 python setup.py bdist_wheel 报错 No module named 'setuptools'。
立即学习“Python免费学习笔记（深入）”；
- 最省事的做法是留一个极简
setup.py，只包含from setuptools import setup; setup()，它会自动 fallback 到pyproject.toml中的[project] - 不要在
setup.py里写逻辑（比如读VERSION文件），否则和pyproject.toml的version不一致，导致安装后importlib.metadata.version("mypkg")返回错误值 - CI 脚本中优先替换为
python -m build --wheel，它原生支持 PEP 621，且不依赖setup.py
动态 version 怎么写才不会被缓存坑死
用 Git 描述符（如 v1.2.0-3-gabc123）生成版本号很常见，但 pip 在 editable 模式下会缓存 pyproject.toml 解析结果，导致改了 commit 后 importlib.metadata.version() 还返回旧值。
性能影响：每次 import 都执行 git describe 会拖慢启动；兼容性影响：某些环境（如 Alpine Linux）没装 git，pip install 直接失败。
- 推荐用
setuptools_scm：在[tool.setuptools_scm]里配version_scheme = "guess-next-dev"，它只在构建时运行一次 git 命令，生成静态version写入 wheel 元数据 - 避免在
[project.version]直接写函数调用，比如"{file:VERSION}"或"{attr: mypkg.__version__}"，这些只在某些工具（如 hatch）里支持，pip原生不认 - 如果必须手动管理，把 version 放进
src/mypkg/_version.py，由构建工具写入，再在pyproject.toml里用[project.dynamic.version]声明，这样 pip 才能识别
tool.* 下的配置项到底谁在读
pyproject.toml 里 [tool.black]、[tool.ruff]、[tool.mypy] 这些段落，Python 解释器完全不看——它们只是各工具约定俗成的存放位置。真正决定行为的是你**实际执行的命令**和**对应工具是否安装**。
容易踩的坑：在 [tool.isort] 里写了 profile = "black"，但没装 isort，结果 pre-commit 钩子静默跳过；或者 [tool.pytest.ini_options] 配了 addopts，但 pytest 版本太老不支持该字段，直接报错退出。
- 每个
[tool.XXX]段落只对XXX工具生效，pip、python、venv全部无视，别指望它们影响 import 行为或虚拟环境创建 - 不同工具对同一名字的字段语义可能冲突，比如
[tool.black.line-length]是 int，但[tool.ruff.line-length]是 string，写错类型会导致工具启动失败 - 想确认某段配置是否生效？直接运行对应命令加
--verbose，例如black --verbose .会打印它加载了哪些配置项
复杂点在于，同一个配置项在不同工具链里可能触发完全不同的行为路径——比如 [project.optional-dependencies] 在 pip install mypkg[dev] 和 poetry add --group dev pytest 中的解析逻辑就不是一回事，别假设“写了就能用”。
