使用Twine上传项目至PyPI失败：Wheel缺失METADATA文件

问题重现 #

执行twine upload dist/*时触发以下错误：

400 Wheel '[modulename]-0.0.1-py3-none-any.whl' does not contain the required METADATA file: [modulename]-0.0.1.dist-info/METADATA

前序操作可能的错误点 #

• 用了非官方的打包方式（比如手动压缩文件），而非标准工具生成wheel
• 缺少pyproject.toml或setup.py的完整配置，导致打包时未自动生成METADATA
• 打包依赖（setuptools、wheel、build）版本过旧或未安装
• 复用了之前生成的有问题的dist文件，未清理旧打包产物

自动生成METADATA并修复报错的步骤 #

1. 配置项目打包文件 #

优先使用Python官方推荐的pyproject.toml，在项目根目录创建该文件，替换成你的项目信息：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "modulename"  # 替换为你的包名
version = "0.0.1"    # 你的版本号
authors = [
  { name="你的名字", email="你的邮箱地址" }
]
description = "你的包的简短描述"
readme = "README.md"
requires-python = ">=3.7"  # 包支持的最低Python版本
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",  # 替换为你的许可证类型
  "Operating System :: OS Independent",
]

如果习惯用setup.py，也可以创建该文件（但更推荐pyproject.toml）：

from setuptools import setup, find_packages

setup(
    name="modulename",
    version="0.0.1",
    author="你的名字",
    author_email="你的邮箱地址",
    description="你的包的简短描述",
    packages=find_packages(),
    python_requires=">=3.7",
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

2. 升级打包依赖 #

执行命令确保工具为最新版本：

pip install --upgrade setuptools wheel build

3. 清理旧文件并重新打包 #

先删除之前生成的错误产物：

# Windows系统执行：rmdir /s /q dist build *.egg-info
rm -rf dist build *.egg-info

用官方工具重新生成符合标准的包：

python -m build

该命令会自动在dist目录生成包含完整METADATA的wheel和源码包。

4. 重新上传至PyPI #

再次执行上传命令：

twine upload dist/*

内容的提问来源于stack exchange，提问作者suley