必须正确配置pyproject.toml中的[build-system]段，否则pip install .或构建wheel会失败或回退旧逻辑；需明确声明requires（构建依赖）和build-backend（构建后端），二者缺一不可。
Python项目用 pyproject.toml 定义构建系统，核心是写对 [build-system] 段，否则 pip install . 或构建 wheel 会失败或退回到旧式逻辑。
必须声明 requires 和 build-backend
这是最常被漏掉的两行。没有它们，现代构建工具（如 pip、build）无法知道该用什么依赖和哪个后端来执行构建：
[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"] build-backend = "setuptools.build_meta"
-
requires列出构建时需要的包（不是运行时依赖），版本要足够新以支持 PEP 517；太老的setuptools<45不识别pyproject.toml配置 -
build-backend必须是可导入的字符串，常见值有："setuptools.build_meta"、"flit_core.buildapi"、"poetry.core.masonry.api"；选错会导致ImportError: cannot import name 'build_wheel' - 如果项目用了
pyproject.toml但没写[build-system]，pip 会回退到setup.py（若存在），或报错No module named 'setuptools'
不要在 [build-system] 里写项目元数据
项目名、版本、作者这些信息不属于构建系统配置，硬塞进去会被忽略——它们该放在 [project] 段（PEP 621）：
[project]
name = "mylib"
version = "0.1.0"
description = "A small example package"
authors = [{name = "Alice", email = "alice@example.com"}]
<p>[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"-
[build-system]只管“怎么构建”，不管“构建什么”；混写会导致工具行为不一致（比如build命令能读[project]，但旧版 pip 可能完全无视） - 若你还在用
setup.py，现在应逐步迁移到[project]：它支持dependencies、optional-dependencies、entry-points等，且无需执行任意 Python 代码 - 注意：某些 backend（如
flit）要求[project]是必需的；而setuptools当前仍兼容空[project]，但不推荐
避免 backend-path 引发的本地路径陷阱
除非你真在开发自定义构建后端，否则不要设 backend-path。它指定本地 Python 模块路径，极易因路径错误或环境隔离导致构建失败：
立即学习“Python免费学习笔记（深入）”；
[build-system] requires = ["setuptools>=45"] build-backend = "my_custom_backend" backend-path = ["./src"] # ⚠️ 大部分人不需要这行
- 设了
backend-path后，构建工具会在该路径下找模块，而不是从sys.path或已安装包中导入；CI 环境或 venv 中很可能找不到 - 错误现象包括：
ModuleNotFoundError: No module named 'my_custom_backend'，即使模块明明在src/下 - 绝大多数项目只需标准 backend（
setuptools/flit/poetry-core），删掉backend-path就能解决 95% 的构建失败
真正容易被忽略的是：不同 Python 版本下，setuptools 对 pyproject.toml 的支持程度不同——3.8+ 更稳，3.7 需手动升级 setuptools 到 45+，否则会静默跳过配置。别只测本地环境，CI 里跑一遍 python -m build --wheel 才算落地。
