GitLab CI作业拉取私有PyPI包报401错误问题排查

GitLab CI作业中使用CI_JOB_TOKEN拉取私有PyPI包报401，核心诱因集中在3类权限和配置问题，和本地个人令牌能正常使用的差异点完全匹配：

• CI Job Token默认跨项目访问被拦截：GitLab默认对自动生成的CI_JOB_TOKEN做了最小权限限制，仅允许访问当前运行CI的项目自身资源。如果你的自研PyPI包存储在其他项目（含同组下的独立项目），没有手动配置访问白名单的话，所有跨项目的包拉取请求都会直接返回401。个人API令牌绑定的是你账号本身的权限，只要你对存包项目有访问权限就能拉取，所以本地环境无问题。
  修复方式：进入存储PyPI包的项目，打开「设置 > CI/CD > Job Token 访问权限」配置页，把当前运行CI作业的项目添加到允许访问的白名单中；如果是同组内多项目共用包仓库，也可以直接开启「允许同组项目通过Job Token访问」的开关。
• URL内嵌认证信息的写法兼容失效：你当前把token直接拼接在extra-index-url中的写法，在pip 21.0以上版本存在认证头透传bug，尤其是GitLab PyPI这种带多层路径的源，很容易出现请求时认证信息丢失的问题，直接触发401。
  修复方式：不要把认证信息拼在URL里，改用pip原生的独立认证配置段，CI作业中直接调用内置的$CI_JOB_TOKEN变量即可，不需要做外部替换，参考配置：

  [global]
  extra-index-url = https://<GITLAB_URL>/api/v4/projects/<PROJECT_ID>/packages/pypi/simple
  
  [extra-index-url:<GITLAB_URL>]
  username = __token__
  password = $CI_JOB_TOKEN
  

• 包仓库权限与令牌角色不匹配：如果存包项目为私有可见，默认CI_JOB_TOKEN的作业角色为访客级别，要是项目的包仓库权限设置为「仅报告者及以上可拉取」，哪怕token本身合法也会被权限拦截返回401。
  修复方式：进入存包项目的「设置 > 通用 > 可见性与权限」页，把包仓库的访问权限下调到访客可访问，或者在CI项目的设置里把Job Token的默认运行角色调整为报告者及以上级别。

快速排查技巧：在CI作业的安装步骤前加pip install -v <PACKAGE_NAME>执行，从debug日志里可以直接看到请求是否携带了正确的认证头，快速区分是权限拦截还是认证信息未透传。

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