Python 适配 semantic-release 使用指南

本文详解了如何正确使用官方维护的 python-semantic-release 工具实现 Python 项目的自动化语义化版本发布，直击常见误区：它并非原版 semantic-release 的简单配置适配，而是完全独立、专为 Python 设计的移植版，仅原生支持 pyproject.toml（PEP 621）中的版本声明，不兼容 setup.py 或 __version__.py——除非显式配置 version_source；同时强调 CI 环境中 Git 用户信息、完整提交历史（fetch-depth: 0）和 token 权限（GitHub/GitLab 推送权限 + PyPI 上传凭证）三大关键配置缺一不可，并明确指出该工具只负责版本管理和 Git 操作，PyPI 上传必须额外集成 build + twine 流程，避免因上传环节缺失导致“有 tag 无包”的典型故障。

semantic-release 默认不支持 Python 项目

它原生只认 JavaScript/TypeScript 的 package.json 和 npm 生态，直接在 Python 项目里跑 semantic-release 命令会报错：Cannot find package.json 或 No version found in package.json。这不是配置问题，是设计限制——它压根没实现对 pyproject.toml、setup.py 或 __version__.py 的解析逻辑。

所以别试“改个配置让它认 Python”，得换思路：

• 用 python-semantic-release（官方维护的 Python 移植版），不是 semantic-release
• 确保安装的是 python-semantic-release，不是同名但无人维护的旧包（PyPI 上有多个相似名）
• 它的 CLI 入口是 semantic-release，但行为完全独立，和 JS 版无共享代码

如何让 python-semantic-release 正确读取版本

它默认只从 pyproject.toml 的 [project.version] 字段读取（PEP 621 标准），不看 setup.py、setup.cfg 或硬编码的 __version__。如果你的项目还在用旧方式，必须迁移或显式配置。

常见适配方式：

• 升级到 PEP 621：在 pyproject.toml 里写 [project] 段并设 version = "0.1.0"
• 若必须用 setup.py，加配置项 version_source = "setup_py" 到 [tool.semantic_release]
• 若版本存在 mylib/__version__.py，设 version_source = "variable" 并配 version_variable = "mylib.__version__:__version__"
• 不推荐用 version_source = "tag"，它只从 Git tag 推断，无法反向写回源码，发布后本地版本号仍为旧值

CI 环境下 token 权限和 Git 配置容易漏

GitHub Actions 或 GitLab CI 里跑 semantic-release 失败，90% 出在 Git 用户身份或 token 权限上。它需要推 tag + 推 commit（比如更新 pyproject.toml 中的版本），不是只读操作。

关键检查点：

• GitHub Actions：用 secrets.GITHUB_TOKEN 即可，但必须设 git config --global user.name 'github-actions' 和 git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
• GitLab CI：CI_JOB_TOKEN 默认无 push 权限，得用 personal access token，并设 git config 同上
• 所有 CI 必须开 fetch-depth: 0（完整历史），否则找不到上次 tag，会误判为首次发布
• 本地测试时，先手动 git tag v0.1.0 && git push origin v0.1.0，再跑 semantic-release publish，避免空历史导致跳过

Python 包发布后 PyPI 上看不到新版本

不是 python-semantic-release 没发，而是它默认只做版本管理和 Git 操作，不上传到 PyPI。上传是单独步骤，得自己配。

典型做法：

• 用 build 打包：python -m build（生成 dist/*.whl 和 dist/*.tar.gz）
• 用 twine 上传：twine upload --repository pypi dist/*
• 把这两步加进 CI 的 semantic-release 成功后的 job，不要混在同一个命令里
• 注意 twine 要用 secrets.PYPI_API_TOKEN，不是 GitHub Token；且 PyPI token 必须有对应项目 maintain 权限

版本号本身没问题，但上传环节掉链子，就会卡在“Git 有 tag，PyPI 没包”这种状态。这地方最容易被当成 semantic-release 本身故障去 debug。

到这里，我们也就讲完了《Python 适配 semantic-release 使用指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！