GitHub Actions发布PyPI失败：Python版本未被识别

排查步骤与修复方案 #

1. 显式指定完整Python版本号 #

确保setup-python动作里明确写全版本号，避免模糊匹配导致版本偏差：

- name: Set up Python 3.9.0
  uses: actions/setup-python@v5
  with:
    python-version: "3.9.0"

不要仅写3.9，部分环境下可能会匹配到同大版本的其他小版本，引发后续版本不匹配问题。

2. 立即验证Python安装状态 #

在setup-python步骤后添加版本验证，确认系统中实际可用的Python版本和路径：

- name: Verify Python installation
  run: |
    python --version
    python3 --version
    which python
    which python3

这一步能快速定位是否存在python命令指向系统自带旧版本（比如Python 2.x）的情况。

3. 强制使用指定版本的Python解释器 #

如果验证发现默认python命令指向错误版本，直接用setup-python提供的环境变量调用正确解释器：

- name: Build package
  run: |
    ${{ env.pythonLocation }}/bin/python -m pip install --upgrade pip setuptools wheel
    ${{ env.pythonLocation }}/bin/python -m build

setup-python会自动设置pythonLocation变量，指向安装的Python根目录，用这个路径调用能彻底避免版本混淆。

4. 检查包配置文件的版本约束 #

确认setup.py或pyproject.toml里的Python版本要求没有冲突：

• 若用setup.py：

  setup(
      ...
      python_requires=">=3.7",
      ...
  )
  

• 若用pyproject.toml：

  [project]
  requires-python = ">=3.7"
  

避免出现意外的严格版本限制导致构建报错。

5. 清理缓存排除干扰 #

GitHub Actions的依赖缓存可能残留旧环境数据，添加缓存清理步骤：

- name: Clear pip cache
  run: pip cache purge

或者直接在setup-python中禁用缓存：

uses: actions/setup-python@v5
with:
  python-version: "3.9.0"
  cache: false

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