重新上传 iOS 构建包到 TestFlight

首次配置。已有的部分可跳过。

• Mac — 必须。iOS 应用只能在 macOS 上构建，Windows/Linux 用户暂不支持。
• Xcode — Apple 的 IDE，归档和上传都需要它，免费。
  • 在 Mac App Store 下载 Xcode ↗（推荐，支持自动更新）
  • 在 developer.apple.com 直接下载 ↗（可选择特定版本，需要登录）
• Apple Developer Program — 每年 99 美元。上传到 TestFlight 或 App Store 需要此资格（免费签名仅支持在自己的设备上运行）。
  • 注册开发者计划 ↗
• App Store Connect 记录 — 您应用的上架条目。在 App Store Connect → My Apps → + ↗ 创建。需要 Bundle ID（例如 com.yourname.appname）和应用名称。
• 可选但实用：Transporter 应用 — Apple 的独立上传工具。在 Mac App Store 下载 Transporter ↗。当 Xcode 内置上传界面出问题时非常好用。
• 可选：App Store Connect API 密钥 — 用于命令行/CI 上传。参见配置 App Store Connect API 密钥。

Apple 会拒绝 CFBundleVersion 相同的重复上传。归档前务必先递增构建号。

在 Xcode 中：点击文件导航栏顶部的项目 → 选择 Target → General → Identity。有两个字段：

• Version（CFBundleShortVersionString）— 用户可见的版本号。修复补丁可保持不变；发布正式更新时递增（如 1.2.0 → 1.2.1）。
• Build（CFBundleVersion）— 加 1。即使 Version 不变，也必须始终递增。

或在项目根目录通过终端执行：

agvtool next-version -all

CFBundleVersion 文档 ↗。

在 Xcode 工具栏（顶部）的设备选择器中，必须选择 Any iOS Device (arm64)，而非模拟器。归档只能针对通用设备目标进行。

菜单路径：Product → Destination → Any iOS Device (arm64)。

在 Xcode 中：菜单选择 Product → Archive。Xcode 将以 Release 模式构建（典型项目需要一两分钟），完成后自动打开 Organizer 窗口并列出您的归档包。

或通过终端：

xcodebuild -scheme YourAppScheme -configuration Release archive \
  -archivePath ~/Desktop/YourApp.xcarchive

分发文档 ↗。

在 Organizer 中（归档完成后自动打开），在左侧选择您的归档包 → 点击右侧的 Validate App。

这一步会在浪费上传时间之前，提前发现签名问题、权限不匹配和 Bundle 配置错误。验证约需 1 分钟。继续操作前请修复所有报错。

方式 A — Xcode Organizer（最简单）。

在 Organizer 中：Distribute App → App Store Connect → Upload。向导会自动完成签名和上传，通常需要 2–5 分钟。

方式 B — Transporter 应用（最稳定）。

先导出 IPA：在 Organizer 中，选择 Distribute App → App Store Connect → Export，保存 IPA 文件。然后打开 Transporter ↗，将 IPA 拖入，点击 Deliver。

当 Xcode 内置上传界面卡住时（这种情况比预期更常见），此方式很有用。

方式 C — 命令行（适合脚本/CI）。

需要先配置 App Store Connect API 密钥，然后执行：

xcrun altool --upload-app \
  -f ~/Desktop/YourApp.ipa \
  -t ios \
  --apiKey "$ASC_KEY_ID" \
  --apiIssuer "$ASC_ISSUER_ID"

App Store Connect API 文档 ↗ · altool 参考 ↗。

上传本身很快（几分钟），Apple 的服务器端处理则需要更长时间：

• 5–15 分钟——正常情况
• 30 分钟–2 小时——繁忙时段（WWDC 周、节假日）
• 处理完成后会收到一封邮件（有时在垃圾邮件文件夹，记得检查）

可在 App Store Connect ↗ → My Apps → 您的应用 → TestFlight 标签页中查看进度。状态流转为：Uploading → Processing → Ready to Submit。

状态变为 Ready to Submit 后，有两种测试人员选项：

• 内部测试 — 自动向您 App Store Connect 团队中最多 100 名用户开放，无需审核，即时可用，适合自有团队和紧密协作者。
• 外部测试 — 通过链接邀请，最多支持 10,000 名测试人员。每个群组的第一个构建需经过 Beta 应用审核（24–48 小时）。后续构建通常可跳过审核，除非有重大变更。

在 App Store Connect 中：TestFlight 标签页 → 点击您的构建 → 切换哪些群组可以访问。测试人员会在 TestFlight 应用中收到推送通知。

测试人员还需要安装 TestFlight 应用 — 在 App Store 下载 TestFlight ↗。如果他们还没有安装，请发给他们链接。

默认情况下，测试人员看到的构建没有任何说明。您可以在 App Store Connect → TestFlight → 您的构建 → Test Details → What to Test 中添加发布说明。测试人员更新时会在 TestFlight 应用中看到这些内容。

说明要简短具体，例如："修复了设置页面的崩溃问题，请尝试切换深色模式。"含糊的说明只会换来含糊的反馈。

• "No signing certificate found" — Xcode → Settings → Accounts → 您的 Apple ID → Download Manual Profiles。或在 Target 的 Signing & Capabilities 标签页中启用 Automatically manage signing。
• "This bundle version is already in use" — 您忘记递增构建号了，返回第 1 步操作。
• "Missing required icon" — 应用图标未填满所有必需尺寸。参考 Apple 图标规范 ↗；appicon.co ↗ 等工具可以从一张图片生成所有尺寸。
• "Invalid entitlements" — 您的 .entitlements 文件中的某项功能未在配置文件中启用。在 developer.apple.com → Identifiers ↗ 中为 App ID 启用该功能，然后重新生成配置文件。
• "ITMS-9000: Bad URL" — Apple 服务器偶发问题，10 分钟后重试。若持续出现，请切换到 Transporter（方式 B）。