如何配置GitHub workflow在Release事件中自动构建Python包wheel并附加到发行版

核心结论 #

可以实现该需求，不需要借助任何额外第三方服务，仅通过GitHub官方自带的Actions功能即可完成全流程。

前置要求 #

你的Python项目根目录需要已配置好合法的构建描述文件（如pyproject.toml），包含正确的包元数据和构建系统声明。

具体配置步骤 #

1. 在你的仓库下创建.github/workflows/目录（如果不存在的话）
2. 在该目录下新建名为release-build.yml的Workflow配置文件，内容如下：

name: Build and upload Python wheel to Release

# 触发规则：仅当发布新Release时触发
on:
  release:
    types: [published]

permissions:
  # 授予写入权限，允许上传资产到Release
  contents: write

jobs:
  build-release:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      - name: 配置Python环境
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: 安装构建依赖
        run: pip install --upgrade build

      - name: 构建wheel包和源码包
        run: python -m build

      - name: 上传构建产物到当前Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release upload ${{ github.event.release.tag_name }} dist/*

配置说明 #

• 触发条件仅匹配正式发布的Release事件，普通提交、PR、草稿Release都不会触发该工作流
• ${{ secrets.GITHUB_TOKEN }}是GitHub自动为工作流生成的临时令牌，不需要你手动配置
• 构建产物默认包含wheel包（.whl）和源码包（.tar.gz），如果你只需要wheel，可以把上传命令改为gh release upload ${{ github.event.release.tag_name }} dist/*.whl

使用方法 #

将上述配置文件推送到仓库的默认分支后，后续你每次创建带标签的新版本Release时，工作流会自动运行，运行完成后刷新对应Release页面即可看到自动上传的构建产物。

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