pyproject.toml 必须存在且包含 [build-system] 和 [project] 两个核心段：前者需声明 requires（如 ["setuptools>=61.0"]）和 build-backend（如 "setuptools.build_meta"），后者必填 name 和 version；缺一则导致 python -m build 或 pip install -e . 失败。
pyproject.toml 必须存在且结构正确
没有 pyproject.toml，python -m build 会回退到旧模式或直接报错，生成的 wheel 可能不被 pip 正确识别。它不是可选配置，而是 PEP 517 的强制入口。
必须包含两个核心段：[build-system] 和 [project]。前者声明构建依赖和后端，后者定义包名、版本、作者等元数据。漏掉任意一个，pip install -e . 或 python -m build 都可能失败。
-
[build-system]中requires至少要含一个构建后端，比如["setuptools>=61.0"]或["hatchling"]；build-backend必须匹配，如"setuptools.build_meta" -
[project]中name和version是必填项；requires-python建议明确（如">=3.8"），否则 CI 上可能因 Python 版本模糊而构建失败 - 如果用
src/布局，[project]里不用写packages字段——现代构建后端（setuptools 61+、hatchling、flit）会自动发现src/<name>目录
src/ 布局比 flat layout 更可靠
把代码放在 src/my_package/ 而不是项目根目录下，能彻底避免 pip install -e . 导致的 import 冲突。常见现象是：本地运行 python -c "import my_package" 成功，但测试时却报 ModuleNotFoundError——大概率是因为当前目录被加进了 sys.path，Python 优先导入了未打包的源码副本，而非安装后的包。
- Cookiecutter 模板（如
audreyr/cookiecutter-pypackage）启用use_src_layout [y]后，自动生成src/my_package/__init__.py和pyproject.toml适配结构 - 手动建
src/时，确保project.name（在pyproject.toml中）与src/下的子目录名完全一致，大小写、连字符都不能错 - 运行
pip install -e .后，检查site-packages是否有my_package-0.1.0-py3.x.egg-link文件，内容应指向你的项目根目录——这是 editable 安装生效的标志
tox + pytest 组合必须隔离 Python 环境
Tox 不是“高级可选工具”，而是验证 PEP 517 包是否真正可复现的关键环节。它强制你在干净虚拟环境中执行 pip install . 和 pytest，暴露那些只在你本机环境里才跑得通的问题。
立即学习“Python免费学习笔记（深入）”；
-
tox.ini中[testenv]的deps = pytest要写在deps下，而不是commands里——否则 pytest 可能用的是系统全局版本，而非 tox 创建的隔离环境里的版本 - 常见错误：
tox -e py39报No module named 'my_package'，90% 是因为pyproject.toml缺少[project]段，或name和实际目录名不一致 - 建议在
tox.ini的commands中加入python -c "import my_package; print(my_package.__file__)"，确认导入的是安装后的包路径，而非源码路径
build 工具比 setup.py 更安全也更可控
python -m build 在临时隔离环境中执行构建，不会污染你当前的 Python 环境，也不执行任意代码——这直接规避了 python setup.py sdist 的安全风险和依赖冲突问题。
- 运行前确认已安装
build：执行pip install build（无需全局升级 pip，build 本身不依赖新版 pip） - 构建命令就是
python -m build，默认同时产出.tar.gz（sdist）和.whl（wheel）；加--wheel或--sdist可单独指定 - 生成的
.whl文件名格式为{name}-{version}-py{X.Y}-{platform}.whl，其中py39表示仅兼容 Python 3.9——若需多版本兼容，确保requires-python设置合理（如">=3.8"），且代码无版本专有语法
[project] 段缺失或字段拼写错误（比如写成 project-name 而非 name），会导致整个构建链路静默失效——既不报错，又生成无效 wheel。务必在 python -m build 后用 pip install --find-links dist/ --no-index my_package 验证安装是否真能成功导入。 
