PyPI认证失败403：如何用API Token通过twine上传Python包？

一、先排查Token核心问题 #

• 确认Token权限：必须是项目级Token（而非账号级只读Token），需勾选「Upload package」权限并关联目标PyPI项目；若用账号级Token，要确保是「Full access」或至少包含上传权限。
• 检查Token有效性：PyPI Token默认无过期时间，但如果手动设置了过期，需重新生成。
• 核对Token一致性：GitHub Secrets中存储的Token要和PyPI生成的完全一致，不能带空格、换行或多余字符。

二、GitHub Action中Twine的正确配置 #

针对你的release.yaml，修正关键步骤：

1. 确保构建合法包产物
   先通过以下命令生成标准的wheel和sdist包：

   python -m pip install --upgrade pip setuptools wheel
   python setup.py sdist bdist_wheel
   

2. Twine上传的标准命令
   不要用旧的无参数上传方式，明确指定用户名和Token：

   python -m pip install --upgrade twine
   python -m twine upload --username __token__ --password ${{ secrets.PYPI_TOKEN }} dist/*
   

   注意：PYPI_TOKEN是你在GitHub仓库「Settings -> Secrets and variables -> Actions」中添加的PyPI Token。

3. 避免环境变量冲突
   检查Action流程中是否有其他设置PYPI_PASSWORD或TWINE_PASSWORD的环节，这些变量会覆盖命令行参数，确保只通过指定的方式传递Token。

4. 强制使用官方PyPI地址
   如果Twine默认配置了镜像地址，可能导致认证失败，明确指定官方上传地址：

   python -m twine upload --repository-url https://upload.pypi.org/legacy/ --username __token__ --password ${{ secrets.PYPI_TOKEN }} dist/*
   

三、本地验证上传（排除Action环境问题） #

先在本地测试Twine上传，确认Token本身有效：

1. 本地生成包：python setup.py sdist bdist_wheel
2. 执行上传命令：

   twine upload --username __token__ --password your_pypi_token_here dist/*
   

   如果本地能成功上传，说明问题出在GitHub Action配置上，回头检查Secrets是否正确、Action步骤是否有冲突。

四、可选方案：切换到可信发布者（更安全） #

如果上述方法仍无法解决，可改用PyPI的可信发布者功能，无需手动管理Token：

• 在PyPI项目的「Settings -> Trusted publishers」中，添加你的GitHub仓库（格式：owner/repo），选择对应的触发环境（比如main分支或Release事件）。
• 在GitHub Action中，替换上传步骤为官方Action：

  - name: Publish to PyPI
    uses: pypa/gh-action-pypi-publish@release/v1
    with:
      packages_dir: dist/
  

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