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免费学习笔记（深入）”；
TURF（开源）权限定制管理系统（以下简称“TURF系统”），是蓝水工作室推出的一套基于软件边界设计理念研发的具有可定制性的权限管理系统。TURF系统充分考虑了易用性，将配置、设定等操作进行了图形化设计，完全在web界面实现，程序员只需在所要控制的程序中简单调用一个函数，即可实现严格的程序权限管控，管控力度除可达到文件级别外，还可达到代码级别，即可精确控制到
- 最省事的做法是留一个极简
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 中的解析逻辑就不是一回事，别假设“写了就能用”。
