Python适配semantic-release教程

本文详解了如何正确使用官方维护的 python-semantic-release 为 Python 项目实现自动化语义化版本发布——它并非原版 semantic-release 的简单配置适配，而是专为 Python 生态重构的独立工具，强制依赖 pyproject.toml（PEP 621）读取版本，并要求 CI 环境严格配置 Git 用户信息、完整提交历史及双因素认证 token 权限；更关键的是，它只负责版本递增、Git 标签与提交，不自动上传包到 PyPI，必须手动集成 build + twine 流程，否则极易陷入“本地有 tag、PyPI 无新版本”的典型陷阱。

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。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。