pyproject.toml必须包含[build-system](含requires和build-backend)与[project](含name、readme、packages等),缺一则构建失败;src布局需显式配置packages,version更新后须清空dist/和build/再重建。

能发,但pyproject.toml必须存在且格式无误,否则python -m build会静默失败或直接报ModuleNotFoundError: No module named 'setuptools.build_meta'——这不是环境问题,是配置缺失。
pyproject.toml 里哪些字段绝对不能少
现代打包只认这个文件,setup.py已彻底退场。漏掉关键段就会构建失败:
-
[build-system]必须显式声明requires和build-backend,哪怕只用setuptools:缺build-backend会导致python -m build找不到构建器 -
[project]中的name决定 PyPI 上的包名(如my-utils),但用户导入时要用下划线(import my_utils);连字符仅用于发布名,不能用于模块名 -
readme = "README.md"必须指向真实存在的文件,否则构建时报FileNotFoundError - 如果源码在
src/目录下(推荐),必须加packages = ["find:"]或显式列出packages = ["my_utils"],否则dist/里是空的
为什么本地 import 成功,但 pip install 后却报 ModuleNotFoundError
打包工具不检查模块能否实际导入,只按配置打包路径。常见原因不是配置错,而是结构和导入路径没对齐:
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期,并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看,该技能
- 确保
src/my_utils/__init__.py存在且非空(哪怕只写__version__ = "0.1.0") - 在项目根目录运行
python -c "import my_utils"应成功;失败说明 Python 没识别到src/,此时要么配packages = ["find:"],要么临时把src/加进PYTHONPATH测试 - 别把
tests/、notebooks/、示例脚本放进src/——它们会被打包进去,且可能因缺失依赖导致用户安装后首次import就崩
twine upload 失败的三个真实原因
401/403 不代表账号密码错,大概率是凭证或包名冲突:
立即学习“Python免费学习笔记(深入)”;
- 用
testpypi测试时,命令必须带--repository testpypi,且~/.pypirc或环境变量中不能混用正式 PyPI 的 token - 报
HTTPError: 400 Client Error: This filename has already been used?PyPI 不允许覆盖同名同版本的.whl或.tar.gz,必须改version后重新build - 上传前没清空
dist/目录,导致旧包和新包一起传——旧包可能已删了__init__.py又重建,PyPI 会拒绝部分文件
最易被忽略的一点:每次改完 version,必须手动删掉 dist/ 和 build/ 目录再 build,否则你传上去的很可能是个半残包。

















