怎么利用强大的Github Actions自动化发布最新Python库到PyPI平台？-Python教程-PHP中文网

GitHub Actions发PyPI包易失败，因缺版本锁、签名校验、环境区分及元数据一致性校验；必须用setup-python+build+twine四步流程，配合Scoped Token和setuptools-scm自动版本管理。

怎么利用强大的github actions自动化发布最新python库到pypi平台？

直接用 setup-python + twine 就能发，但不加版本锁、不校验签名、不区分测试/正式环境，发出去的包大概率会让人 pip install 失败或运行出错。

为什么 GitHub Actions 发 PyPI 包容易失败

常见错误现象包括：HTTPError 403（API token 权限不足）、InvalidDistribution（build 没生成 wheel）、twine check 报 warning 后被 PyPI 拒收、或者用户装上后提示 ModuleNotFoundError —— 这些都不是网络问题，而是流程缺了关键校验环节。

根本原因是：PyPI 对上传包的元数据、构建产物、签名一致性要求严格，而本地开发时往往跳过 pyproject.toml 的 [project] 字段校验、忽略 build-system.requires 声明、甚至用 python setup.py sdist 这种已弃用方式构建。

必须用 build 工具（不是 setuptools 的旧命令）生成 sdist 和 wheel
twine check 必须在上传前运行，且不能有 WARNING
__version__ 必须从 pyproject.toml 读取，不能硬编码在 __init__.py 里
PyPI token 只能用于 pypi.org，测试用 test.pypi.org 必须换另一套 token

GitHub Actions 中必须写的 4 个关键步骤

一个最小可行发布流水线，不是“跑通就行”，而是要让每次 git push --tags 都触发一次可审计、可回退的发布。这四步缺一不可：

用 actions/checkout@v4 拉代码，并启用 fetch-depth: 0（否则 git describe 拿不到 tag）
用 actions/setup-python@v5 指定 Python 版本，并显式运行 python -m pip install build twine
用 python -m build --sdist --wheel --no-isolation 构建（--no-isolation 避免重复安装 build-system.requires）
用 twine upload --repository pypi dist/*，其中 --repository 必须在 .pypirc 或环境变量中预置，不能写死密码

注意：build 默认不生成 .tar.gz，必须加 --sdist；如果只传 dist/*.whl，Windows 用户可能装不上，因为没提供源码分发包。

PyPI token 怎么配才安全又可用

GitHub Secrets 里存的不是用户名密码，而是 PyPI 提供的 Scoped Token（形如 pypi-xxxxx），它只能上传指定包名，且可随时撤销。配置时容易踩两个坑：

Lingxi · Webhook Dispatcher with GitHub API Fallback

智能 Webhook 分发器，支持 GitHub API 回退机制。当 Git 推送失败时，自动路由至 GitHub Contents API。支持重试逻辑、del…

下载

Secret 名必须是 PYPI_API_TOKEN（或其他你代码里引用的变量名），不能叫 token 或 api_key —— 否则 twine 不识别
不能把 token 写进 .pypirc 文件再 commit，必须通过 env: 注入到 twine upload 步骤中，例如：
```
env:<br>  TWINE_USERNAME: __token__<br>  TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
```
测试环境应使用 test.pypi.org，对应 Secret 名建议为 TEST_PYPI_API_TOKEN，避免误发到正式源

如果你发现 twine upload 报 Invalid or non-existent authentication information，八成是 TWINE_USERNAME 没设成 __token__，这是 PyPI 强制要求的 magic string。

版本号怎么自动从 git tag 提取并同步到包元数据

手动改 pyproject.toml 里的 version 容易漏，推荐用 setuptools-scm 自动推导。但它在 GitHub Actions 里有个隐藏依赖：必须确保 checkout 时带完整历史，且 tag 已存在。

配置要点：

pyproject.toml 中删掉 [project].version 字段，换成：

[tool.setuptools-scm]<br>version_file = "src/my_package/_version.py"

CI 步骤中，在 pip install build twine 后，加一句 pip install setuptools-scm（否则 build 不认识该插件）
确保推送 tag 的命令是 git tag v0.1.0 && git push origin v0.1.0，而不是 git push --tags（后者可能推送未命名分支的临时 tag）