trumandu--myboot/docs/pypi-publishing.md

PyPI 自动发布配置指南

本文档说明如何配置 GitHub Actions 自动发布到 PyPI。

工作流说明

项目已配置 GitHub Actions 工作流 (.github/workflows/publish.yml)，当创建新的 tag（以 v 开头，如 v1.0.0）时，会自动构建并发布到 PyPI。

配置 Trusted Publishing（推荐方式）

Trusted Publishing 是 PyPI 推荐的安全发布方式，无需使用 API token，通过 OIDC 进行身份验证。

步骤 1: 在 PyPI 上配置 Trusted Publisher

1. 登录 PyPI
2. 进入您的项目页面
3. 点击左侧菜单的 "Publishing" 或 "Manage" → "Publishing"
4. 在 "Trusted publishers" 部分，点击 "Add"
5. 填写以下信息：
   • PyPI project name: myboot（您的项目名称）
   • Publisher name: 自定义名称，如 github-actions
   • Workflow filename: publish.yml
   • Environment name: 留空（或填写特定环境名称）
   • GitHub Owner: 您的 GitHub 用户名或组织名
   • GitHub Repository: myboot（您的仓库名）
   • Workflow filename: publish.yml
6. 点击 "Add" 保存

步骤 2: 验证配置

配置完成后，当您创建新的 tag 时，GitHub Actions 会自动触发发布流程：

# 创建并推送 tag
git tag v1.0.0
git push origin v1.0.0

工作流会自动：

1. 检出代码
2. 安装构建依赖
3. 构建分发包（wheel 和 sdist）
4. 使用 trusted publishing 发布到 PyPI

使用 API Token 方式（备选）

如果您不想使用 trusted publishing，也可以使用传统的 API token 方式：

步骤 1: 创建 PyPI API Token

1. 登录 PyPI
2. 进入 "Account settings" → "API tokens"
3. 点击 "Add API token"
4. 填写：
   • Token name: 如 github-actions-publish
   • Scope: 选择 "Project: myboot"（项目范围）或 "Entire account"（账户范围）
5. 复制生成的 token（只显示一次，请妥善保存）

步骤 2: 在 GitHub 中配置 Secret

1. 进入您的 GitHub 仓库
2. 点击 "Settings" → "Secrets and variables" → "Actions"
3. 点击 "New repository secret"
4. 填写：
   • Name: PYPI_API_TOKEN
   • Secret: 粘贴刚才复制的 API token
5. 点击 "Add secret"

步骤 3: 修改工作流文件

修改 .github/workflows/publish.yml，添加 password 参数：

- name: Publish to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    password: ${{ secrets.PYPI_API_TOKEN }}
    print-hash: true

注意: 使用 API token 会禁用 trusted publishing，但两种方式不能同时使用。

Tag 命名规则

工作流配置为匹配以 v 开头的 tag：

• ✅ v1.0.0 - 匹配
• ✅ v0.1.0 - 匹配
• ✅ v2.3.4 - 匹配
• ❌ 1.0.0 - 不匹配（缺少 v 前缀）
• ❌ release-1.0.0 - 不匹配

发布流程

1. 更新版本号: 在 pyproject.toml 中更新 version 字段
2. 提交更改: 提交并推送代码到仓库
3. 创建 Tag: 创建并推送以 v 开头的 tag
4. 自动发布: GitHub Actions 会自动触发发布流程

# 示例流程
# 1. 更新 pyproject.toml 中的版本号
# version = "1.0.0"

# 2. 提交更改
git add pyproject.toml
git commit -m "Bump version to 1.0.0"
git push

# 3. 创建并推送 tag
git tag v1.0.0
git push origin v1.0.0

验证发布

发布完成后，您可以：

1. 在 PyPI 项目页面 查看新版本
2. 使用 pip 安装测试：

   pip install myboot==1.0.0
   

故障排查

问题 1: Trusted Publishing 配置失败

错误信息: 403 Client Error: Invalid or non-existent authentication information

解决方案:

• 检查 PyPI 上的 trusted publisher 配置是否正确
• 确认 GitHub 仓库名称、工作流文件名等信息匹配
• 确保工作流文件中的 permissions 包含 id-token: write

问题 2: 版本已存在

错误信息: File already exists

解决方案:

• 检查 PyPI 上是否已存在该版本
• 如果确实需要重新发布，需要先删除 PyPI 上的版本（不推荐）
• 或者使用新的版本号

问题 3: 构建失败

错误信息: 构建步骤失败

解决方案:

• 检查 pyproject.toml 配置是否正确
• 确认所有必需的文件都已包含在分发包中
• 查看 GitHub Actions 日志获取详细错误信息

参考资源

• PyPI Trusted Publishers 文档
• pypa/gh-action-pypi-publish 项目
• PyPI 发布指南