如何在GitHub Actions中发布到TestPyPI时避免无效版本号？

按照Python官方指南配置GitHub Actions，实现Python包自动发布到PyPI，同时每次推送代码时发布到TestPyPI服务器，但上传时遇到报错：版本号包含Git哈希值（如0.1.dev1+g18d1902），TestPyPI拒绝接受这类本地版本号。已知需要移除哈希部分，但不清楚具体实现方法，还担心会导致包版本重复无法上传。

错误信息 #

400 The use of local versions in <Version('0.1.dev1+g18d1902')> is not allowed

当前GitHub Actions配置片段 #

publish-to-testpypi:
  name: Publish to TestPyPI
  needs:
  - build
  runs-on: ubuntu-latest

  environment:
    name: testpypi
    url: https://test.pypi.org/p/{{package name}}

  permissions:
    id-token: write

  steps:
  - name: Download all the dists
    uses: actions/download-artifact@v4
    with:
      name: python-package-distributions
      path: dist/
  - name: Publish distribution to TestPyPI
    uses: pypa/gh-action-pypi-publish@release/v1
    with:
      verbose: true
      repository-url: https://test.pypi.org/legacy/

解决方案 #

1. 移除版本号中的Git哈希后缀 #

TestPyPI和PyPI均遵循PEP 440规范，不允许带+号的本地版本标识。要去掉Git哈希部分，需从版本生成环节调整：

• 若使用setuptools_scm自动生成版本，在pyproject.toml中添加配置：

  [tool.setuptools_scm]
  local_scheme = "no-local-version"
  

  配置后生成的版本号会从0.1.dev1+g18d1902变为0.1.dev1，符合TestPyPI的要求。

2. 避免TestPyPI包版本重复 #

直接使用0.1.dev1这类固定dev版本号会导致重复上传被拒，TestPyPI不允许相同版本号多次发布。可以通过以下方式生成唯一版本号：

• 方法一：结合GitHub Actions运行编号
  在build任务中添加步骤，动态生成包含运行编号的版本号：

  - name: 生成动态版本号
    run: echo "VERSION=0.1.dev${{ github.run_number }}" >> $GITHUB_ENV
  

  然后在pyproject.toml中读取该环境变量作为版本：

  [project]
  version = "${VERSION}"
  

  （需确保构建工具支持环境变量替换，若使用setuptools，可能需要配合setup.py读取环境变量）

• 方法二：自定义setuptools_scm版本格式
  保留Git哈希但调整格式，将+替换为.（符合PEP 440规范），比如生成0.1.dev1.g18d1902：

  [tool.setuptools_scm]
  local_scheme = "node-and-hash"
  

  该格式既包含Git哈希信息，又能被TestPyPI接受，同时保证每个提交的版本号唯一。

3. 配套调整构建流程 #

如果使用动态版本号，需确保在build任务中先设置好版本变量，再执行python -m build等构建命令，这样生成的包才会带有正确的唯一版本号，避免上传失败。

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