DEBUG.WIKI
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国
搬瓦工;先看线路,再选 VPS;CN2 GIA · 对应线路套餐;查看线路 →
V.PS:让项目靠近用户,亚太、欧洲、北美 KVM VPS

Twine 6.2 报 Metadata 2.5 无效,检查旧版格式白名单

Twine 6.2.0 覆盖 packaging 的有效版本列表,导致合法的 Core Metadata 2.5 被拒绝。7.0.0 已去掉旧覆盖;更新实际检查环境后,对原产物重新执行本地 check。

构建 wheel 和 sdist 已成功,Twine 6.2.0 在本地检查时却拒绝它们:

InvalidDistribution: Invalid distribution metadata:
'2.5' is not a valid metadata version

这里的 2.5 是发行包的 Core Metadata 格式版本,不是项目版本号,也不是 Python 2.5。即使环境已经安装较新的 packaging,旧 Twine 仍可能报同样的错误。

原因在 Twine 6.2.0:它为兼容历史 Metadata 2.0,覆盖了 packaging 的有效元数据版本列表,列表只到 2.4。因此,构建后端生成合法的 Metadata-Version: 2.5 时,也会被这层旧列表拒绝。

检查构建工具与检查工具各自的环境

先保留已经构建好的文件,确认实际执行检查的工具版本:

python -m twine --version

在 CI、Pixi、pipx 或独立上传 Action 中,检查器可能有自己的工具环境。给开发环境更新 packaging,不会自动改变那个环境里的 Twine;6.2.0 的覆盖逻辑也不只是补一个新 packaging 就能消除。

Twine 7.0.0 已正式去掉这项旧覆盖,并明确支持 Metadata 2.5。它要求 Python 3.10 或更新版本,以及符合依赖声明的 packaging 等组件。应更新实际做发行检查的工具环境,保留项目的版本约束和可恢复配置。

如果上传流水线封装了独立 Action,还要核对它内部使用的 Twine,而不是只看上游构建步骤输出的新版本。固定的 Action 提交不会因另一步安装了新版 Twine 就自动改变。

先验证同一份产物,不直接重试发布

更换检查环境后,对保留的那一组产物重新执行本地检查,例如:

python -m twine check --strict dist/example_pkg-1.0.0-py3-none-any.whl

将示例路径换成实际 wheel,并单独覆盖对应 sdist。这条检查不会上传文件;仍应阅读全部结果,确认没有变成说明格式、缺失字段等其他错误。

不要解压 wheel 后手工把 Metadata-Version 从 2.5 改成 2.4,也不要修改 Twine 或 packaging 的私有版本列表。降低数字可能掩盖格式语义,并破坏发行文件的完整性;若确实需要更旧的元数据格式,应由支持该配置的构建后端重新生成并重新检查整套产物。

7.0.0 同时取消了对未正式标准化的 Metadata 2.0 的特殊容忍,不能认为更新后所有历史包都更宽松。若旧产物恰好声明 2.0,应回到构建过程修正。

本地检查通过只完成发行前的一项验证。远端仓库的格式支持、认证和实际上传结果仍需分别确认,不能由这一条错误消失推断包已经发布。