python-semantic-release是官方维护的Python适配版，需从pyproject.toml读取版本，默认不支持setup.py或__version__.py，CI需配置Git用户信息和完整历史，发布后需手动用build+twine上传到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__。如果你的项目还在用旧方式，必须迁移或显式配置。
常见适配方式：
立即学习“Python免费学习笔记（深入）”；
- 升级到 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。
