使用twine向GitLab包仓库发布多Python版本wheel时pip仅可安装最后上传版本的问题

该问题是低于14.2版本的GitLab Package Registry的已知实现缺陷：

• 低版本GitLab的PyPI端点在生成simple索引页时，未按包版本维度聚合关联的所有发行文件，仅保留最新上传的单文件链接，直接覆盖同包同版本下之前上传的其他发行物的索引项。
• 你之前验证的“单独上传某版本wheel可正常安装、手动下载多版本wheel可正常使用”的现象，完全匹配该缺陷的表现：所有上传的文件确实存储在Registry中，但索引仅指向最后一次上传的文件，其余文件未被索引列出，因此pip在安装时无法检索到匹配当前Python环境的发行包。

1. 根本解决方式：升级GitLab实例 #

将GitLab实例升级至14.2及以上版本即可彻底修复该问题：

• 该版本正式优化了PyPI Repository的多发行物索引逻辑，支持同一包版本下共存多个不同Python tag、平台tag的wheel或源码分发包；生成的simple索引会列出该版本下关联的所有发行物，pip可根据当前运行环境自动匹配对应版本的包文件。

2. 低版本实例的临时规避方案 #

如果无法立即完成GitLab版本升级，可通过调整CI上传逻辑规避索引覆盖问题：

• 移除三个独立并行上传的构建Job，改为两阶段流水线结构：
  • 第一阶段：三个Python版本的构建Job仅负责生成对应wheel文件，将生成的wheel存储为CI artifact，配置artifacts.when: always确保所有构建产物可被后续Job访问。
  • 第二阶段：新建一个发布Job，通过needs配置依赖所有构建Job完成，从各Job的artifact路径中拷贝全部wheel文件到统一的dist目录，再执行一次twine上传操作。
• 规避原理：当twine一次性上传多个同版本的wheel文件时，GitLab端点会将所有文件关联到同一包版本下，触发全量索引生成，避免逐Job独立上传时反复覆盖索引的问题。

3. 常见配置校验项 #

如果调整流水线后仍存在安装匹配问题，可逐一排查以下配置：

• 确认生成的wheel文件命名符合PEP 427规范：你当前设置的py{major}{minor}格式的Python tag合法，none-any的abi/平台tag匹配纯Python包的特征，无需调整。
• 确认权限配置：使用CI_JOB_TOKEN上传时，对应Job需具备包上传权限；使用个人Token拉取安装时，Token需包含read_package_registry权限。

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