Pilot (Fastlane)：核心概念、TestFlight 以及移动项目的构建版本管理

什么是 Pilot (Fastlane)？

Pilot (Fastlane) — 是 Fastlane 生态系统中的一个组件，用于自动化与 TestFlight（Apple 的移动应用程序测试版测试平台）的工作。Pilot 接管所有日常操作：上传构建版本、添加测试人员、管理组以及跟踪构建状态。

没有 Pilot，测试版的分发过程如下：开发人员手动打开 App Store Connect，选择应用程序，通过 Xcode Organizer 上传 IPA，配置测试人员组并发送邀请。TestFlight — 是 Apple 的服务，用于在应用程序正式发布到 App Store 之前在测试人员之间分发测试版。

根据 App Store Connect Help（2025），外部测试人员必须在首次安装构建版本之前通过 Beta App Review 流程 — 这需要 1 到 48 小时。Pilot 自动跟踪审核状态，并在构建版本准备好分发给外部测试人员组时通知团队。

在任何需要定期向测试人员交付测试版构建版本的项目中使用 Pilot — 这是 iOS 应用程序 CI/CD 流水线的标准工具，确保可预测的交付过程。

Pilot 用于 TestFlight 的主要功能

Pilot 的功能 涵盖测试版构建版本管理的完整生命周期：从上传二进制文件到通知测试人员新版本。每个功能都作为独立的命令实现，具有可预测的行为和每个步骤的详细日志记录。

将构建版本上传到 TestFlight

fastlane pilot upload 命令将 IPA 文件上传到 App Store Connect 并在 TestFlight 中创建新的构建版本。Pilot 自动检查二进制文件的有效性、版本和应用程序标识符的匹配。App Store Connect — 是 Apple 的应用程序管理平台，包括上传构建版本、元数据、分析和销售报告。

上传后，Pilot 等待 Apple 处理二进制文件 — 该过程需要 5 到 30 分钟，具体取决于构建版本的大小。在等待期间，Pilot 显示进度条，其中包含有关当前处理状态的信息：Processing、Validating 或 Ready。成功处理后，构建版本即可分配给测试人员组。

管理测试人员组

Pilot 支持管理内部和外部测试人员组。内部测试人员 — 是您 Apple Developer 团队的成员，无需通过 Beta App Review 即可立即访问构建版本。外部测试人员 — 是通过电子邮件邀请的用户，需要在首次安装之前获得审核批准。

fastlane pilot add 命令通过电子邮件或 Apple ID 将新测试人员添加到组中。Pilot 自动发送邀请并检查测试人员是否已接受邀请。对于批量添加，可以通过 --testers_file_path 参数从文件传递电子邮件列表，这在初始收集有数百名参与者的测试人员组时很方便。

# 将新构建版本上传到 TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# 将测试人员添加到组
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pilot 的安装和配置

Pilot 的配置 不需要单独的配置文件 — 设置通过 Appfile（共享的 Fastlane 文件）或命令行参数传递。主要参数包括应用程序的 apple_id、app_identifier、team_id 以及用于访问 App Store Connect API 的凭据。

对于身份验证，Pilot 使用 App Store Connect API Key（推荐方法）或 Apple ID 双因素身份验证。App Store Connect API Key — 是在 App Store Connect 中生成的访问密钥，允许在无需交互式输入密码和确认码的情况下与 API 进行交互。

# Appfile — Fastlane 通用配置
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Pilot 的环境变量
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

app_identifier 参数确定应用程序的 Bundle Identifier，该标识符必须与 Xcode 项目和 App Store Connect 中指定的标识符匹配。apple_id 参数用于双因素方案中的身份验证，team_id 用于选择开发团队（如果帐户关联了多个 Apple Developer 团队）。

要使 Pilot 工作，需要在 CI/CD 环境中配置 App Store Connect API Key。该密钥在 App Store Connect → Users and Access → Keys → Generate API Key 中生成。将 .p8 文件保存在 CI 系统的密钥中，并通过环境变量 APP_STORE_CONNECT_API_KEY_PATH 或 Pilot 命令中的 --api_key_path 参数指定其路径。

用于管理构建版本的 Pilot 命令

Pilot 命令集 涵盖与 TestFlight 合作的所有场景：上传构建版本、管理测试人员、查看状态和跟踪元数据。每个命令都返回结构化的 JSON 输出，以便在 CI/CD 脚本中进行进一步处理。

查看构建状态

fastlane pilot builds 命令显示应用程序所有构建版本的列表，包括版本、处理状态和上传日期。构建状态 可以是以下之一：Processing — Apple 正在处理二进制文件，Ready — 构建版本可用于分发，Rejected — 由于验证错误，构建版本被拒绝。

# 查看 TestFlight 中所有构建版本的列表
fastlane pilot builds

# 将构建版本分配给测试人员组
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# 查看特定构建版本的信息
fastlane pilot build_info --build_number 42

fastlane pilot distribute 命令将构建版本分配给指定的测试人员组并发送通知。--notify 参数启用向测试人员发送有关新可用构建版本的电子邮件通知 — 这对于让测试版测试人员参与测试过程以及加速反馈至关重要。

对于构建版本元数据的管理，使用 --changelog 参数，该参数设置新版本中变更描述的文本。此文本在 TestFlight 应用程序的测试邀请中向测试人员显示。建议在每个构建版本中提及关键变更、已修复的错误和新功能。

Pilot 在 CI/CD 流水线中的集成

CI/CD 中的 Pilot — 是 iOS 应用程序交付流水线的最后阶段。在 Gym 构建了 IPA 并且测试通过后，Pilot 将构建版本上传到 TestFlight 并分发给测试人员组。这使 QA 团队能够在提交到仓库后几分钟内收到应用程序的新版本。

典型的 iOS CI/CD 流水线包括以下序列：Match（证书）、Gym（构建 IPA）、Pilot（上传到 TestFlight 和分发）。每个阶段都依赖于前一个阶段，这确保了只有有效且经过签名的构建版本才能交付给测试人员。

# Fastfile 中的完整流水线
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

upload 命令中的 skip_waiting 参数允许在 CI 任务范围内不等待 Apple 完成二进制文件的处理 — Pilot 发送上传请求，接收构建版本标识符，然后结束工作。这加速了流水线，因为处理可能需要长达 30 分钟，这些时间不会浪费在 CI 运行器的等待上。

为了使 Pilot 在 CI 中正常工作，需要配置 App Store Connect API 密钥。将 .p8 密钥文件保存在 CI 系统的安全存储中，并通过环境变量 APP_STORE_CONNECT_API_KEY_PATH 传递路径。Pilot 使用此密钥在没有双因素身份验证的情况下进行 API 身份验证，这对于自动化场景至关重要。

使用 Pilot 时的常见问题

在使用 Pilot 时，开发人员最常见的问题是身份验证错误、应用程序配置不正确以及 Apple 处理二进制文件的问题。问题诊断 Pilot 从通过 pilot builds 命令检查 App Store Connect 中的构建状态开始。

«Your app is not available for testing in TestFlight» 错误发生在应用程序未在 App Store Connect 中配置为测试时。解决方案：在 App Store Connect 中打开 TestFlight 部分，为应用程序激活测试，并确保 Export Compliance 已针对您的加密类型正确填写。

«Missing iOS Distribution signing identity» 错误表明 Keychain 中缺少 Distribution 证书。解决方案：在调用 Pilot 之前运行 Match 以加载正确的证书。Distribution 证书 与 Development 不同 — 它用于签署旨在通过 TestFlight 或 App Store 分发的构建版本。

在 «Invalid Provisioning Profile» 错误中，构建版本包含对所选导出方法不正确的配置文件。解决方案：检查 Gym 是否使用了与 Match 中的配置文件类型相对应的正确 export_method。如果构建版本是使用开发配置文件构建的，Pilot 将无法将其上传到 TestFlight — 需要 app-store 或 ad-hoc 配置文件。