当前位置：首页 > news >正文

Hackers发布流程完全指南：从TestFlight到App Store的完整流程

news 2026/7/13 14:46:21

Hackers发布流程完全指南：从TestFlight到App Store的完整流程

【免费下载链接】HackersHackers is an elegant iOS app for reading Hacker News written in Swift.项目地址: https://gitcode.com/gh_mirrors/ha/Hackers

Hackers是一个优雅的iOS Hacker News阅读应用，采用SwiftUI和Swift Package Manager模块构建。本指南将详细介绍Hackers应用的完整发布流程，涵盖从版本准备、TestFlight测试到App Store发布的每一个关键步骤。无论您是新手开发者还是经验丰富的iOS工程师，这份终极指南都将帮助您掌握Hackers应用的发布全流程。

🚀 发布流程概览

Hackers采用标签驱动的发布模型，每个TestFlight构建都使用完整的语义版本+构建号标签：v<MARKETING_VERSION>+<CURRENT_PROJECT_VERSION>。例如v5.3.2+160表示营销版本5.3.2，构建号160。

整个发布流程分为三个阶段：

版本准备- 更新版本号和应用内容
TestFlight发布- 构建、上传和分发测试版本
App Store发布- 提交到App Store审核

📋 发布前准备检查清单

在开始发布之前，请确认以下准备工作已完成：

✅master分支通过所有必需检查：lint、build、test和ui smoke
✅testflightGitHub环境已配置并需要审批
✅ App Store Connect API密钥具有读取构建、上传构建、更新TestFlight元数据等权限
✅ match仓库包含两个Bundle ID的签名资产：
- com.weiranzhang.Hackers
- com.weiranzhang.Hackers.ActionExtension

🔧 版本准备步骤

1. 确定版本类型

首先决定这是新的营销版本还是当前营销版本的另一个构建：

# 查看当前版本信息 cat docs/release-process.md | grep -A 5 "Release Model"

2. 更新版本号

需要更新两个目标的版本号：

Hackers- 主应用目标
HackersActionExtension- 操作扩展目标

在Hackers.xcodeproj中更新：

MARKETING_VERSION- 控制发布家族（如5.3.2）
CURRENT_PROJECT_VERSION- 控制App Store Connect构建号

3. 更新应用内容

如果构建包含用户可见的更改，需要更新应用内的"What's New"内容。相关代码位于Features/WhatsNew/模块中。

4. 本地验证

在提交前进行本地验证：

# 运行测试套件 ./run_tests.sh # 运行UI烟雾测试 ./run_ui_tests.sh smoke

5. 提交发布准备更改

在通过所有必需检查后，将发布准备更改提交到master分支：

git add . git commit -m "Prepare release vX.Y.Z+N" git push origin master

🏷️ 创建标签并触发TestFlight

标签格式要求

标签格式必须为v<MARKETING_VERSION>+<CURRENT_PROJECT_VERSION>：

# 示例标签 tag=v5.3.2+160 # 创建标签 git tag "$tag" master git push origin "refs/tags/$tag"

触发TestFlight工作流

标签推送会自动触发.github/workflows/release-testflight.yml工作流。您也可以在GitHub Actions中手动触发：

# 手动触发 gh workflow run release-testflight.yml -f release_tag=v5.3.2+160

审批保护环境

TestFlight工作流运行在受保护的testflightGitHub环境中，需要手动审批。在GitHub Actions界面中批准部署请求。

📝 TestFlight发布说明管理

TestFlight工作流会在上传前解析artifacts/release/what-to-test.txt，并为标签创建或更新GitHub Release。草稿发布使用前一个标签的生成说明，已发布的发布使用前一个已发布版本的生成说明。

手动创建发布说明

如果需要手动创建或替换发布说明：

tag=v5.3.2+160 gh release create "$tag" \ --target "$tag" \ --title "${tag#v}" \ --notes-file release-notes.txt \ --draft

编辑现有发布

gh release edit "$tag" --title "${tag#v}" --notes-file release-notes.txt

发布为App Store候选版本

当TestFlight说明完成后，将GitHub Release发布为公开状态：

gh release edit "$tag" --draft=false

🔍 监控TestFlight上传

监控工作流进度

# 查看最近的工作流运行 gh run list --workflow release-testflight.yml --limit 5 # 监控特定运行 gh run watch <run-id> --exit-status

预期成功日志里程碑

✅Archive Succeeded
✅Successfully exported and signed the ipa file
✅Successfully uploaded package to App Store Connect
✅Successfully finished processing the build
✅Successfully set the changelog for build
✅Successfully distributed build to External testers
✅Uploaded Hackers X.Y.Z (N) to TestFlight

验证构建状态

工作流成功完成后，在App Store Connect中确认构建出现且状态为VALID。GitHub工作流摘要会记录标签和上传的构建号。

📱 在App Store Connect中验证

成功上传后，需要验证以下内容：

构建状态- 确认构建在App Store Connect/TestFlight中显示为有效
处理状态- 确保构建处理完成且无错误
版本匹配- 验证版本号和构建号与标签匹配
测试分发- 确认已正确分发到外部测试组

✍️ 编写App Store发布说明

重要提示：App Store发布说明与GitHub Release正文和TestFlight"What to Test"文本不同。它们是面向App Store客户的最终公开产品文案。

发布说明规则

✅ 专门为公开的App Store列表编写
✅ 用通俗语言总结用户可见的更改
✅ 保持简洁，对决定是否更新的用户有用
❌ 不要包含GitHub比较链接、Full Changelog链接、PR链接、issue链接、提交哈希
❌ 不要粘贴GitHub Release正文或TestFlight说明而不为这个受众重写
❌ 不要包含生成的变更日志部分、Markdown标题或测试说明

发布说明示例

好的示例：

"改进Feed浏览体验并修复读者报告的问题。优化了评论加载性能，增强了搜索功能。"

不好的示例：

"修复了#123问题，合并了PR #456。完整变更日志：https://github.com/... 测试说明：请检查..."

🚀 提交到App Store审核

前提条件

仅在人工审查选定构建和最终自定义App Store发布说明后，才推广已验证的TestFlight构建。

提交命令

gh workflow run release-appstore.yml \ -f release_tag=v5.3.2+160 \ -f app_store_release_notes='改进Feed浏览体验并修复读者报告的问题。'

可选输入参数

build_number- 仅当明确选择已处理的App Store Connect构建时使用
skip_app_version_update- 跳过创建或更新App Store版本
cancel_pending_version- 提交前取消待处理的App Store版本
cancel_only- 仅取消待处理版本而不提交构建

工作流保护

App Store提交工作流同样运行在受保护的testflightGitHub环境中，需要人工审批。不要提交最终说明是从GitHub/TestFlight内容复制或包含返回GitHub链接的构建。

🛠️ 故障处理与恢复

发布失败处理步骤

不要删除密钥或签名资产- 在确认错误前不要更改敏感信息
检查失败日志- 查看失败的作业日志和上传的testflight-artifacts
修复自动化或项目签名问题- 在master分支上修复问题
推送修复- 将修复推送到仓库
移动发布标签- 仅当失败的标签未产生可用的TestFlight构建时，将发布标签移动到修复后的提交
批准新的TestFlight部署- 批准新的受保护TestFlight部署并监控其完成

强制移动失败标签

仅在TestFlight构建成功完成前，强制移动失败的发布标签：

tag=v5.3.2+160 git tag -f "$tag" HEAD git push --force origin "refs/tags/$tag"

重要：一旦TestFlight构建成功完成，将标签视为不可变的。

🔄 现有草稿发布修复

如果需要修复使用旧版说明生成逻辑创建的现有草稿发布：

GITHUB_REPOSITORY=weiran/Hackers for tag in $(gh release list --json tagName,isDraft --limit 200 --jq '.[] | select(.isDraft == true).tagName'); do # 处理逻辑... done