🚀 发布流程实施指南 (Release Process Implementation Guide)

版本: v1.0.0 | 最后更新: 2025-12-26 | 作者: AI Assistant

🎯 概述

本文档详细记录了项目中的PyPI包发布实施过程、具体配置步骤和问题解决方案。

📋 PyPI发布完整流程

1. 🔧 发布准备阶段

Trusted Publisher配置

[ ] 访问 PyPI Publishing Settings
[ ] 点击 "Add" 添加新的pending publisher

[ ] 填写配置信息：

PyPI Project Name: mddocx
Owner: wangqiqi
Repository name: md2docx
Workflow name: publish.yml
Environment name: (留空)

[ ] 配置完成后会出现在"Pending publishers"列表中
[ ] 注意: 如果项目不存在，第一次发布会自动创建项目

Trusted Publisher故障排查

常见错误: invalid-publisher: valid token, but no corresponding publisher解决方案:

确认PyPI配置完全匹配
等待5-10分钟生效
检查workflow文件名是否正确
使用手动发布作为备用方案

版本单一真源（勿再增 VERSION 文件）

角色	文件	说明
权威	`pyproject.toml` → `[project].version`	打包、运行时（`mddocx.__version__`）均由此读取
门面	`README.md` badge · `CHANGELOG.md` 段落 · git tag `v*`	给人看 / 发版记录；须与 pyproject 一致
校验	`bash scripts/verify_release_alignment.sh`	CI 与 `/release` 前自动核对上述一致性

运行时 mddocx.__version__ 不硬编码：源码树读 pyproject.toml，已安装 wheel 读 distribution metadata。

门面一致性（打 tag / push 前必跑）

bash

# 本地：pyproject / __version__ / README badge / CHANGELOG / license 表格式
bash scripts/verify_release_alignment.sh

# 打 tag 时额外校验 tag 与 pyproject 一致
EXPECT_TAG=v0.5.49 bash scripts/verify_release_alignment.sh

CI quality 与 publish.yml（tag 推送）均会自动执行；verify_release_candidate.sh 也会先跑对齐检查。

检查项	失败含义
`license = {text = "MIT"}`	勿用 SPDX 字符串 `license = "MIT"`（Python 3.8 CI 会挂）
README badge = `pyproject.version`	门面版本不一致
`CHANGELOG` 含当前版本段、`[Unreleased]` 无未折叠条目	发版文档未就绪
`EXPECT_TAG` 与 `pyproject` 一致	tag 打在错误 commit 上

Trusted Publisher 发布失败（与对齐无关）

若 publish.yml 在 Publish to PyPI 步骤失败并打印 claims 信息，说明 PyPI 项目未配置或未生效 Trusted Publisher，不是代码/版本问题。

打开 mddocx PyPI Publishing
添加 Pending publisher（须与 publish.yml claims 完全一致）：
- Publisher: GitHub
- Owner: wangqiqi
- Repository: md2docx
- Workflow name: publish.yml（仅文件名）
- Environment: 留空
保存后等待 5–10 分钟再重推 tag，或 Actions → Publish to PyPI → Run workflow 手动重跑
备用：本地 python -m build && ./scripts/publish_to_pypi.sh（API token）

本地验证

[ ] 发布候选预检（推荐）：bash scripts/verify_release_candidate.sh
聚合 pytest（覆盖率 ≥85%）、flake8、black、mypy、isort、ConvertMetrics、python -m build + twine check、wheel 卫生检查、隔离安装后 pip check / CLI 转换 / WebUI 资源冒烟，并提示 PyPI 版本碰撞（当前 pyproject.toml 版本已发布时，后续 /release 须升下一 patch）。
[ ] 构建包：python -m build
[ ] 检查包：twine check dist/*
[ ] 测试安装：pip install dist/mddocx-<version>-py3-none-any.whl（<version> 与 pyproject.toml 一致）

2. 🚀 发布执行阶段

自动发布（推荐）

bash

# 推送版本标签，自动触发发布
git tag -a v0.4.3 -m "Release version 0.4.3"
git push origin v0.4.3

手动发布（备用）

bash

# 如自动发布失败，使用脚本
./scripts/publish_to_pypi.sh

3. ✅ 发布验证阶段

PyPI可用性检查

[ ] 访问 PyPI项目页面
[ ] 确认版本 0.4.3 已发布
[ ] 检查包文件完整性

安装测试

bash

# 清除缓存后安装
pip install --no-cache-dir --index-url https://pypi.org/simple/ mddocx==0.4.3

# 验证安装
python -c "import mddocx; print(f'✅ 版本: {mddocx.__version__}')"

# 运行基本功能测试
python -c "from mddocx import BaseConverter; print('✅ 导入成功')"

⚠️ 常见问题与解决方案

Trusted Publisher配置失败

错误: The publisher is not configured for this project

解决方案：

确认PyPI项目所有权
检查GitHub仓库名称拼写
等待PyPI配置生效（可能需要几分钟）

包发布延迟

包在PyPI搜索中不可见

解决方案：

等待10-30分钟让索引同步

直接使用PyPI官方源安装：

bash

pip install --index-url https://pypi.org/simple/ mddocx

权限问题

错误: 403 Forbidden

解决方案：

验证PyPI API token权限
检查Trusted Publisher配置
确认GitHub Actions有正确的权限

📊 发布监控

GitHub Actions监控

访问: https://github.com/wangqiqi/md2docx/actions/workflows/publish.yml
查看发布工作流执行状态
检查详细日志了解失败原因

发布后 PyPI 版本核对（E-PUB-01）

publish.yml 在 Trusted Publisher 成功后会自动执行：

bash

# CI 内（带重试）：PYPI_RETRIES=3 PYPI_RETRY_SLEEP=8
bash scripts/verify_pypi_version.sh "${GITHUB_REF_NAME#v}"

结果	含义
步骤绿	PyPI JSON API 已能查到该版本的 `mddocx`
步骤红	上传可能成功但索引延迟，或发布未真正生效；查看 Actions 日志后可本地复跑
Trusted Publisher 失败	不会进入核对步骤；job 以 `exit 1` 失败，并打印配置提示

本地手工核对（已发布版本应退出 0）：

bash

bash scripts/verify_pypi_version.sh 0.5.49
# 可选重试：PYPI_RETRIES=3 PYPI_RETRY_SLEEP=5 bash scripts/verify_pypi_version.sh <version>

索引偶发延迟时，CI 默认重试 3 次、间隔 8 秒，降低误红概率。

PyPI状态监控

项目页面: https://pypi.org/project/mddocx/
下载统计: https://pypi.org/project/mddocx/#files
依赖检查: https://pypi.org/project/mddocx/#dependencies

🔄 发布后的维护

版本管理

[ ] 更新CHANGELOG.md记录发布内容
[ ] 创建GitHub Release说明
[ ] 更新文档中的版本信息

监控与支持

[ ] 监控PyPI下载统计
[ ] 处理用户反馈和问题报告
[ ] 准备下一个版本的改进计划

📚 相关链接

通用发布管理规范（项目内未单独维护，以本文与 CHANGELOG 为准）
PyPI官方文档
Trusted Publisher指南

🚀 发布流程实施指南 (Release Process Implementation Guide) ​

🎯 概述 ​

📋 PyPI发布完整流程 ​

1. 🔧 发布准备阶段 ​

Trusted Publisher配置 ​

Trusted Publisher故障排查 ​

版本单一真源（勿再增 VERSION 文件） ​

门面一致性（打 tag / push 前必跑） ​

Trusted Publisher 发布失败（与对齐无关） ​

本地验证 ​

2. 🚀 发布执行阶段 ​

自动发布（推荐） ​

手动发布（备用） ​

3. ✅ 发布验证阶段 ​

PyPI可用性检查 ​

安装测试 ​

⚠️ 常见问题与解决方案 ​

Trusted Publisher配置失败 ​

包发布延迟 ​

权限问题 ​

📊 发布监控 ​

GitHub Actions监控 ​

发布后 PyPI 版本核对（E-PUB-01） ​

PyPI状态监控 ​

🔄 发布后的维护 ​

版本管理 ​

监控与支持 ​

📚 相关链接 ​

🚀 发布流程实施指南 (Release Process Implementation Guide)

🎯 概述

📋 PyPI发布完整流程

1. 🔧 发布准备阶段

Trusted Publisher配置

Trusted Publisher故障排查

版本单一真源（勿再增 VERSION 文件）

门面一致性（打 tag / push 前必跑）

Trusted Publisher 发布失败（与对齐无关）

本地验证

2. 🚀 发布执行阶段

自动发布（推荐）

手动发布（备用）

3. ✅ 发布验证阶段

PyPI可用性检查

安装测试

⚠️ 常见问题与解决方案

Trusted Publisher配置失败

包发布延迟

权限问题

📊 发布监控

GitHub Actions监控

发布后 PyPI 版本核对（E-PUB-01）

PyPI状态监控

🔄 发布后的维护

版本管理

监控与支持

📚 相关链接