iOS 构建

使用Capgo的专用Mac基础设施，构建并提交iOS应用到TestFlight和App Store。

你将学到什么

• 你将学习如何通过Capgo Native Build上传你的应用
• 你将学习如何配置Capgo Native Build的证书

前置条件

• Capgo 帐户（具有有效订阅）
• Capgo 中已注册的应用（如果没有，请运行 bunx @capgo/cli@latest app add 一台mac电脑，安装了Xcode（可以在linux/windows机器上设置构建，但尚未文档）
• 有效的Apple Developer帐户（$99/年）（您必须在Apple Developer帐户上具有管理员或所有者权限）
• 通过Xcode成功构建应用
• __CAPGO_KEEP_0__ 应用
• Capacitor 应用
• 注意

__CAPGO_KEEP_0__

我将使用以下应用进行教程： https://github.com/Cap-go/capgo-native-build-tutorial-app

在苹果门户中开始之前

在设置证书或触发首次 TestFlight 上传之前，确保 Apple 帐户和团队准备就绪：

• 为用于注册的 Apple 帐户启用两因素身份验证
• 选择正确的会员类型：
  • 个人/独资：您的法律个人姓名将成为 App Store 上的卖家名称
  • 组织：需要一个法律实体、一个 D-U-N-S 编号、一个公共公司网站、一个公司域名的工作电子邮件以及一个具有权力将组织绑定到苹果协议的个人
• 使用可以访问苹果开发者和 App Store Connect 的帐户，用于证书、应用记录、API 密钥和 TestFlight
• 尽早锁定您的最终 bundle ID。稍后改变它通常意味着重新设置 App Store
• 在 App Review 前，务必规划这些 App Store Connect 项：支持 URL、隐私政策 URL、年龄等级、截图、出口遵从性和 App Review 联系方式

注意

有用的官方参考：

• 加入 Apple 开发者计划
• 提交您的应用和游戏
• App Store Connect 中的平台版本信息

注意

苹果会定期更新其最低SDK要求。截至 2026年4月28日, iPhone和iPad应用程序上传到App Store Connect必须使用 iOS & iPadOS 26SDK或更高版本.

第一个手动构建

在我们开始思考如何使用Capgo构建应用程序之前，我们应该首先设置它，并手动完成第一次TestFlight构建。 手动构建有几个优势：

• 您将在本地机器上设置分发证书
• 您将创建App Store记录，如果您尚未完成，请务必完成
• 您将能够解决与应用程序code相关的构建过程中的任何问题

在开始之前，您必须在本地机器上安装分发证书。 这很复杂，但我将在下面解释。

设置分发证书

1. 打开Xcode

2. 点击 Xcode -> Settings... 或者，您可以使用快捷方式 Cmd + ,

   

3. 前往 Accounts

4. 找到已添加到Apple Developer帐户的Apple帐户

5. 找到您将用于部署应用程序的团队

6. 点击 Manage Certificates... 按钮

7. 确保您可以在列表中看到分发证书

8. 如果您无法看到，请创建新的证书

   注意

   苹果限制您可以拥有的分发证书数量为 3。如果您有超过 3 个证书，则需要删除一个以创建新的一个。该教程将不覆盖此内容。

   1. 点击 + 按钮，然后点击 Apple Distribution
   2. 证书将自动创建。您可以在列表中看到它。查看上一步以确认您看到它。

您已安装分布式证书，现在可以开始构建过程。

手动构建到 TestFlight

1. 在 Xcode 中打开应用

   运行 bunx cap open ios 在 Xcode 工具栏中找到并点击

2. 按钮 archive 在 Xcode 工具栏中找到并点击

   按钮 product -> archive 手动构建到 TestFlight

   

3. 等待构建完成

4. 点击 Distribute App 按钮

   

5. 选择 TestFlight Internal Only 作为发布方法并点击 Distribute 按钮

   

6. 配置应用记录

   填写以下字段:

   1. 名称：您的应用程序名称 - 在App Store中可见
   2. SKU - 应用程序的 SKU - 这是用于在 App Store 中识别您的应用程序的 SKU
   3. The primary language - 应用程序的主要语言

   然后，点击 next 按钮

   

7. 如果创建应用程序记录失败，请尝试关闭窗口并尝试再次存档应用程序。

8. 等待上传完成

9. 如果一切顺利，您应该看到以下屏幕

10. 点击 Done 按钮

您可能会本能地认为现在一切都好，并且您将能够在 TestFlight 中看到您的应用程序，但仍有几个事情需要完成：

1. 加入 TestFlight
2. 完成出口遵从性检查，才能让构建变成可测试的
3. 填写 App Store Connect 必填的元数据，如支持 URL、隐私政策 URL 和年龄等级
4. 准备与您实际支持的设备匹配的截图
5. 在生产提交之前添加 App Review 联系信息和任何测试凭证

好的，我们从第一步开始：

加入 TestFlight

1. 前往 App Store Connect 页面

2. 使用您的Apple Developer账户登录

3. 选择您在创建应用记录时使用的团队。如果您只有一份开发者账户，可以跳过这个步骤。

4. 点击 Apps App Store Connect应用按钮

5. App Store Connect应用选择

6. App Store Connect测试飞行按钮 TestFlight 点击

7. 点击 Internal Testers plus button

8. 创建一个新组

   我喜欢将组命名为“内部”。你可以给它任何名字。

   

9. 点击 Invite testers button

10. 将自己添加到组中

    在列表中找到并选择下面你的名字旁边的复选框。 (你可能需要刷新页面才能看到自己) 然后，点击 Add button

    

11. 确认您已加入群组

    现在，您应该在群组中看到自己。

    

恭喜 🎉 您已将自己添加到 TestFlight 中。现在，还有一件事您需要做才能配置 Capgo Native Build。

设置合规信息

您现在需要向 Apple 保证您的应用程序不使用任何非标准（如自定义算法）加密。如果您的应用程序确实使用任何非标准加密，我建议阅读 Apple 文档 关于如何处理此问题的说明。 有两种方法可以做到这一点：

1. 您可以每次构建应用程序时都手动完成此操作。
2. 您可以配置您的 plist 文件，以自动将此值设置为 false.

让我们从第一种方法开始：

1. 按照上一节的步骤，找到 TestFlight 部分在 App Store Connect 中

2. 点击 Builds -> iOS

3. 找到缺少合规信息的构建并点击 Manage

4. 选择描述您的应用程序的最佳选项

   对于我来说，这是 none但这可能与您不同。 然后点击保存

   

5. 您的应用程序现在应该显示 ready to test

   

至于第二个，步骤如下：

1. 打开 Info.plist 文件

2. 添加以下键值对：

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. 保存文件

注意

这里 是苹果官方文档关于如何告知苹果您遵守加密出口规则的说明。

安装TestFlight应用并接受邀请

现在，您已经 即将准备好测试您的应用程序。 在此之前，您需要完成以下步骤：

1. 下载 TestFlight 应用程序
2. 从 App Store 上的 iOS/iPadOS 设备上

接受测试您的应用程序的邀请

我将跳过如何在您的设备上安装 TestFlight 应用程序的详细信息。如果您不确定如何安装应用程序，请参阅 Google 的有关安装应用程序的指南。

1. 至于接受邀请，您将收到来自 Apple 的一封电子邮件，其中包含一个链接以接受邀请。

2. 打开来自 Apple 的电子邮件，包含接受邀请的链接 View in TestFlight 点击

3. 点击 Install 按钮

4. 在您的设备上安装应用

   如果您以前使用 Xcode 安装了应用，则可能会看到以下屏幕。请点击 install 按钮。

5. 等待应用安装

6. 点击 Open 按钮并点击它

恭喜 🎉 您已接受 TestFlight 测试应用的邀请。现在，您可以配置 Capgo Native Build 来构建和提交应用到 TestFlight。

配置 Capgo Native Build

为了能够构建并将应用程序提交到 TestFlight，您需要配置以下几项内容在Capgo本机构建中。 以下是您将传递给CapgoCLI的内容列表。

参数	描述
--platform	要构建的平台（ios)
--apple-team-id	您的Apple开发者团队ID（在 Apple开发者门户)
--apple-key	您的App Store ConnectAPI密钥文件路径（.p8 文件）
--apple-key-id	您的App Store ConnectAPI密钥的Key ID
--apple-issuer-id	您的App Store Connect发行者ID
--certificate	您的分发证书路径（.p12 文件)
--ios-provisioning-profile	配置文件映射（bundleId=path 或仅为单个配置文件路径)

示例命令：

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

团队 ID

让我们从团队 ID开始。找到它很容易。

1. 前往 Apple Developer Account 并向下滚动

2. 找到 Team ID

   

Apple 密钥、Apple 密钥 ID 和 Apple 发行者 ID

现在，让我们继续到 Apple 密钥。

1. 前往 App Store Connect 用户和访问页面

   注意

   对于我来说，链接有时不起作用。 如果它对你也没有用，请重新加载页面。

2. 从下拉菜单中选择正确的团队

   1. 单击顶部右侧的您的姓名
   2. 点击您要使用的团队

3. 点击 Integrations 按钮

4. 找到 issuer

   注意

   这是 需要保存 -您稍后会需要它

   点击 copy __CAPGO_KEEP_0__

5. 点击加号按钮

6. 设置密钥名称并设置访问权限 App manager 并点击 Generate 按钮

7. 保存密钥ID

   注意

   此 需要保存 - 您稍后会需要它

   

8. 下载密钥

   注意

   这个 需要保存 - 您稍后会需要它

   危险

   绝不与任何人共享密钥 - 只在 CAPGO CLI 中使用

   

   

恭喜你 🎉 你已经创建了Apple密钥、Apple密钥ID和Apple发行者ID。

证书

现在，你准备好导出证书了。回想一下，这个指南的第一步是设置分布式证书。

然而，苹果在他们的无限智慧中决定了你导出证书的方式与创建它们的方式有所不同 🙃 让我们进入设置：

1. 打开Keychain Access

   1. 点击 Command + Space 以打开搜索栏
   2. 搜索 Keychain Access
   3. 点击 Keychain Access app

2. 选择 login 类别并点击 My Certificates 按钮

3. 在列表中找到您的证书

   证书应该命名为 Apple Distribution: [Your Name/Company] (your team ID)

4. Keychain Access 导出证书 Export

5. __CAPGO_KEEP_0__ .p12 文件

   注意

   请确保保存 __CAPGO_KEEP_0__ -稍后会需要它

   1. 请为证书文件选择一个合适的名称
   2. 请确保文件格式设置为 Personal Information Exchange (.p12)
   3. 点击 Save 按钮

   

6. 当被要求输入密码时，您可以选择:

   • 跳过密码（推荐简化）：点击 OK 不输入密码
   • 设置密码：如果您希望用密码保护证书， .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password 文件完全支持

   

7. 钥匙串访问保存证书密码对话框

   当被要求输入“登录钥匙串密码”时，请输入您用来登录Mac的密码 Allow 输入您用来登录Mac的密码。然后，点击

   

钥匙串访问保存证书登录钥匙串密码

恭喜 🎉 您已成功导出证书。

现在，您已经准备好从 Apple 导出配置文件。 我保证，这是您从 Apple 需要的最后一件事。

1. 前往 Apple Developer 个人资料

2. 在下拉菜单中选择正确的团队

   1. 点击右上角的您的姓名
   2. 点击要使用的团队

3. 确保您位于正确的页面 如果不是，请点击 profiles 在侧边栏中

   

4. 点击 + 按钮

5. 选择个人资料类型 选择 App Store Connect 并点击 Continue 按钮

   

6. 选择您要构建的应用

   在下拉菜单中找到您的应用并点击 Continue 按钮

   

7. 选择正确的分发证书

   选择您在上一步中导出的证书并点击 Continue 按钮

   

   如果您不确定要选择哪个证书，请返回 Keychain Access，找到您导出的证书，然后查看有效期。

   

8. 命名配置文件

   为配置文件命名并点击 Generate 提示

   配置文件名称将自动由 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 提取 — 您不需要记住它。

   The profile name is automatically extracted by the Capgo CLI — you don’t need to remember it.

   

9. 下载配置文件

   点击下载 Download __CAPGO_KEEP_0__配置文件

   注意

   这个文件 需要保存 - 后续会用到

   

恭喜 🎉 您现在已经准备好配置Capgo原生构建了。

注意

不要将您刚刚创建的凭证提交到您的仓库。 请妥善保管！ 🔒

运行配置命令

恭喜您！您已经准备好配置 Capgo Native Build 了。

您需要运行的命令是：

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

替换占位符值

将上面的占位符值替换为您在前一步骤中收集的实际凭据：

• --apple-team-id您的Apple Team ID
• --apple-key您下载的密钥文件路径 .p8 替换上述占位符值
• --apple-key-id: Your Apple Key ID
• --apple-issuer-id: Your Apple Issuer ID
• --certificate: Path to your exported .p12 证书
• --ios-provisioning-profile: Path to your downloaded .mobileprovision 文件（bundle ID根据单个配置文件自动推断）

如果一切顺利，您将看到以下输出：

CI/CD 设置 (GitHub Actions)

如果您已经完成了 团队 ID, Apple key, Apple key ID 和 Apple issuer ID, 证书, 和 分发配置文件, 您已经拥有CI/CD所需的所有内容。 本节仅介绍如何将这些值作为 GitHub Actions 秘密和环境变量传递。

1) 将凭据文件转换为单行base64

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

提示

GitHub 秘密应为单行值。 tr -d '\n' 去除 base64 输出中的换行符。

2) 创建仓库密钥

在 GitHub > Repository > Settings > Secrets and variables > Actions密钥名称

值	您的 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ token
CAPGO_TOKEN	Your Capgo API token
APP_STORE_CONNECT_TEAM_ID	团队 ID 密钥 ID
APPLE_KEY_ID	Apple 密钥，Apple 密钥 ID 和 Apple 发行商 ID 在此处添加：
APPLE_ISSUER_ID	发行者 ID Apple key、Apple key ID 和 Apple 发行者 ID
BUILD_CERTIFICATE_BASE64	文件内容 certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	由 CLI 生成 — 从 .capgo-credentials 文件
APPLE_KEY_CONTENT	文件内容 apple_key_base64.txt
P12_PASSWORD (可选)	您的 .p12 密码（如果在导出期间设置）

3) 在您的 GitHub Actions 工作流中使用环境变量

github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

提示

通过此设置，CI 只通过环境变量发送凭据。您不需要提交签名文件或将它们作为工作流文件上传。

运行构建

现在，您已经准备好运行第一个构建。

要构建您的应用，请运行以下命令：

bunx @capgo/cli@latest build request --platform ios

恭喜 🎉 您已经成功构建了应用程序，并且它已经准备好提交到 App Store。

适配性发布模式

默认情况下，Capgo 构建 iOS 应用程序以供 App Store 分发（TestFlight + App Store）。如果您需要即用即发构建（用于内部测试或 CI artifact 收集），则可以使用 --ios-distribution 标志。

注意

即用即发分发 不是 与企业（内部）分发相同。企业分发需要单独的 Apple Developer Enterprise 账户，并使用不同的配置文件。Capgo 目前支持 app_store 和 ad_hoc 模式。

何时使用即用即发模式

• 您想直接将 IPAs 分发给注册的设备（不使用 TestFlight）
• 您没有或不想使用 App Store Connect API 密钥
• 您想通过 --output-upload 而不提交到 App Store

要求

Ad-hoc 构建有 比 App Store 构建少的要求： 凭证

是否需要？	分发证书（
Distribution certificate（.p12)	是
自定义配置文件 (.mobileprovision)	是
团队 ID (--apple-team-id)	是
App Store Connect API 密钥 (.p8)	否
Apple Key ID / 发行者 ID	否

注意

在 ad_hoc 模式，和 --apple-key, --apple-key-id不受支持且被忽略。 这是为什么上面两个App Store Connect行不显示ad-hoc__CAPGO_KEEP_0__标志的原因；这些选项仅适用于 --apple-issuer-id are not supported and are ignored. This is why the two App Store Connect rows above do not show ad-hoc CLI flags; these options apply to app_store 注意

创建一个adhoc配置文件

Without an App Store Connect API key, build number auto-increment uses a timestamp-based fallback. To suppress the warning, pass --skip-build-number-bump.

按照相同的步骤

，但在第五步中选择 targetLanguageSimplified Chinese 即用型 而不是 App Store:

1. 前往 Apple Developer Profiles
2. 点击 + 按钮
3. 选择 即用型 并点击继续
4. 选择您的应用程序和分发证书
5. 选择您要注册的设备
6. 下载并命名配置文件

保存临时凭证

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

否 --apple-key, --apple-key-id, 或 --apple-issuer-id 需要。

运行临时构建

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

为了收集 IPA 作为构建 artifact，添加 --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD 与 ad-hoc 构建

对于 GitHub Actions，您需要比 App Store 构建少的密钥：

github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

提示

注意到 APPLE_KEY_ID, APPLE_ISSUER_ID，和 APPLE_KEY_CONTENT 不需要为即时构建使用。

包含扩展的应用（多目标签名）

如果您的应用包含扩展（共享扩展、小部件、通知服务扩展等），则每个扩展目标都需要自己的签名配置文件。Capgo通过可重复的 --ios-provisioning-profile 标志支持此功能。

示例：应用+共享扩展

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

标志映射一个bundle ID到其签名配置文件。__CAPGO_KEEP_0__: --ios-provisioning-profile flag maps a bundle ID to its provisioning profile file. The CLI:

1. 读取每个mobileprovision文件
2. 自动提取嵌入的 plist 中的 profile 名称
3. 以 Base64 编码文件
4. 将所有内容存储为一个 CAPGO_IOS_PROVISIONING_MAP 凭据

提示

您需要为所有目标使用一个分布式证书 — 只有分发配置文件才会根据目标而异。

从单一配置文件迁移

如果您以前使用过 BUILD_PROVISION_PROFILE_BASE64 (单一配置文件)，请运行：

bunx @capgo/cli build credentials migrate --platform ios

将您的现有单一配置文件凭据转换为新格式并删除遗留密钥（ CAPGO_IOS_PROVISIONING_MAP 迁移后，使用以下命令（累积合并）添加扩展配置文件：BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

终端窗口 update 复制到剪贴板

bunx @capgo/cli build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

(not

) update Use save(not update 命令合并新配置文件与现有配置文件。使用 save 仅在从头开始设置所有凭证时使用。

Troubleshooting

配置文件中没有包含 XYZ 能力。

有时，您可能会看到以下错误：

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

这发生在您在创建配置文件后启用了新能力之后。 旧的配置文件还没有包含新能力。

要解决这个问题，您需要重新生成配置文件。

1. 打开 Apple Developer Portal
2. 选择正确的团队
3. 点击 Profiles Apple Developer profiles按钮
4. Apple Developer查找配置文件
5. Apple Developer编辑配置文件 Edit 点击
6. __CAPGO_KEEP_0__ Save __CAPGO_KEEP_1__
7. 点击 Download 按钮
8. 重新运行 Capgo 原生构建设置命令 使用刚下载的配置文件。

这应该解决问题。

其他问题

If for whatever reason you are having issues either with Capgo Native Build, configuring the credentials or building the app, please don’t hesitate to reach via our 编辑页面.