iOS Builds

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

使用Capgo专属的Mac硬件，构建并提交iOS应用到TestFlight和App Store。

What you will learn

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

Prerequisites

一个Capgo账户（免费试用即可开始）
您的应用已经在Capgo中注册（如未注册，请运行 bunx @capgo/cli@latest app add 一台Mac电脑，安装了Xcode（可以在linux/windows机器上设置构建，但尚未文档）
有效的Apple Developer账户（$99/年）(您必须在Apple Developer账户上具有管理员或拥有者权限)
一台Mac电脑，安装了Xcode（可以在linux/windows机器上设置构建，但尚未文档）
您的应用程序必须能够通过Xcode进行成功的构建
一个Capacitor应用
一个已配置的应用程序图标。没有图标的应用程序无法上传到App Store。

在Apple的门户网站中开始之前

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

为用于注册的Apple账户启用两因素身份验证
选择正确的会员类型：
- 个人/独资企业:您的法律姓名将成为App Store上的卖家名称
- 组织:需要一个法律实体，一个D-U-N-S号，一个公共公司网站，一个公司域名的工作电子邮件，以及一个有权代表组织与Apple协议的个人
使用一个可以访问Apple Developer和App Store Connect的帐户来获取证书，应用程序记录，API密钥和TestFlight
尽早锁定您的最终bundle ID。改变它后通常需要重新设置App Store
在App Review之前，计划这些App Store Connect项目：支持URL，隐私政策URL，年龄等级，截图，出口合规性和App Review联系方式

不需要手动操作。Capgo的自动注册功能会为您创建和配置iOS签名凭证（分发证书+分发配置文件）— 这是推荐的路径：

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

以下手动步骤仅适用于那些愿意自己设置凭证或了解Capgo背后的工作原理的人。

第一个手动构建

在使用Capgo构建应用之前，我们应该先设置它，并手动完成第一个TestFlight构建。手动构建有几个优势：

您将在本地机器上设置分发证书
您将创建App Store记录，如果您尚未完成此步骤
您将能够找出与应用code相关的构建过程中的任何问题

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

设置分布式证书

打开Xcode
点击 Xcode -> Settings... 或者您可以使用快捷方式 Cmd + ,
前往 Accounts
找到已添加到Apple Developer帐户的Apple Account
找到您将用于部署应用的团队
点击 Manage Certificates... 按钮
确保您可以在列表中看到分发证书
如果您无法看到，请创建新的证书

苹果限制您可以拥有的分发证书数量为3。如果您有超过3个证书，则需要删除一个以便创建新的一个。该教程将不覆盖此操作。
1. 点击 + 按钮，然后点击 Apple Distribution
2. 将证书自动创建。您可以在列表中看到它。查看前一步以确认您看到它。

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

手动构建到 TestFlight

在 Xcode 中打开应用

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

在 Xcode 工具栏中找到并点击 product -> archive Xcode 工具栏
等待构建完成
点击 Distribute App 按钮
选择 TestFlight Internal Only 作为发布方法并点击 Distribute 按钮
配置应用记录

填写以下字段：
1. 名称：您的应用名称 - 在App Store中可见
2. SKU - 应用程序的SKU - 在App Store中用于识别应用程序
3. 应用的主要语言
然后，点击 next __CAPGO_KEEP_0__
如果创建应用记录失败，请尝试关闭窗口并尝试再次存档应用。
等待上传完成
如果一切顺利，您应该看到以下屏幕
点击 Done 您可能会本能地认为现在一切都好，并且您将能够在 TestFlight 中看到您的应用，但仍有几件事情需要完成：

将自己添加到 TestFlight 中

__CAPGO_KEEP_1__
确保构建符合出口控制要求，使其可用于测试
填写必填的App Store Connect元数据，例如您的支持URL、隐私政策URL和年龄等级
准备与您实际支持的设备匹配的截图
在生产提交之前添加App Review联系信息和任何测试凭证

让我们从第一个开始：

添加自己到TestFlight

前往 App Store Connect App Store Connect
使用您的Apple Developer帐户登录
选择您在创建应用记录时使用的团队。如果您只有一份开发者账户，可以跳过这个步骤。
点击 Apps App Store Connect应用按钮
App Store Connect应用选择
App Store Connect测试按钮 TestFlight 点击
点击 Internal Testers plus App Store Connect测试按钮
创建新组

我喜欢将组命名为“内部”。你可以给它任何名字。
点击 Invite testers 按钮
将自己添加到组中

在列表中找到并选择你自己的名字旁边的复选框。 (你可能需要刷新页面才能看到自己) 然后，点击 Add 按钮
验证你已经添加到组中

现在，你应该在组中看到自己了。

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

设置合规信息

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

你可以每次构建应用程序时都手动完成此步骤。
你可以配置plist文件来自动设置此值为 false.

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

按照上一节中的所有步骤找到App Store Connect中的TestFlight部分
点击 Builds -> iOS
找到缺少合规信息的构建并点击 Manage
选择描述您的应用程序的最佳选项

对于我来说，这是 none,但可能与您不同。然后点击保存
您的应用程序现在应该显示 ready to test

至于第二个，步骤如下：

打开 Info.plist file

添加以下密钥：

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

保存文件

安装TestFlight应用并接受邀请

现在，您已经接近准备好在 TestFlight 中测试您的应用。在此之前，您需要完成以下步骤：

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ 从 App Store 下载
TestFlight

应用

在您的 iOS/iPadOS 设备上

接受测试您的应用的邀请
如果您不确定如何安装应用，请参阅 Google 的相关指南。 View in TestFlight 您将收到来自 Apple 的一封电子邮件，包含接受邀请的链接。
点击 Install button
在您的设备上安装应用

如果您以前使用Xcode安装了应用，可能会看到以下屏幕。请单击 install button
等待应用安装
单击 Open button

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

配置Capgo Native Build

您需要在Capgo原生构建中配置一些东西才能构建和提交您的应用到TestFlight。以下是您将传递给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开始。找到它很容易。

前往 Apple Developer Account 并滚动到底部
找到 Team ID

Apple key、Apple key ID 和 Apple 发行者 ID

现在，让我们继续 Apple key。

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

有时链接无法正常工作。请尝试重新加载页面。
从下拉菜单中选择正确的团队
1. 点击右上角的用户名
2. 点击要使用的团队
点击 Integrations button
找到 issuer

这是 需要保存 - 你以后会需要它

点击 copy 按钮复制发行者
点击加号按钮
设置密钥的名称并设置访问权限 App manager 并点击 Generate 按钮
保存密钥 ID

这 必须保存 - 您稍后需要它
下载密钥

这 必须保存 - 您稍后会需要它

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

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

证书

现在，您已经准备好导出证书。您还记得本指南的第一步是设置分发证书吗？

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

打开钥匙串访问
1. 点击 Command + Space 打开搜索栏
2. 在搜索栏中查找 Keychain Access
3. 点击 Keychain Access 应用
选择 login 类别并点击 My Certificates 按钮
在列表中找到您的证书

证书名称应为 Apple Distribution: [Your Name/Company] (your team ID)
右键单击证书并选择 Export
将证书保存为 .p12 文件

请 必须保存 - 您稍后会需要它
1. 确保为证书文件选择一个合适的名称
2. 确保文件格式设置为 Personal Information Exchange (.p12)
3. 点击 Save 按钮
当被要求输入密码时，您可以选择：
- 跳过密码（推荐简化）：点击 OK 不输入密码
- 设置密码：如果您希望保护证书使用密码，可以在此处设置一个。使用密码保护的 .p12 文件完全支持 Capgo CLI - 只需在运行配置命令时使用 --p12-password Keychain Access 保存证书密码对话框
当被要求输入“登录钥匙串密码”，给出您用来登录 Mac 的密码

输入您用于登录 Mac 的密码。然后，点击 Allow 按钮。

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

配置文件

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

前往 Apple Developer Profiles
从下拉菜单中选择正确的团队
1. 点击右上角的您的姓名
2. 点击您要使用的团队
确保您在正确的页面它应该看起来像这样，如果它不点击 profiles 侧边栏
点击 + 按钮
选择配置文件类型选择 App Store Connect 并点击 Continue 按钮
选择您要构建的应用

在下拉菜单中找到您的应用程序并点击 Continue button
选择正确的分发证书

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

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

为配置文件命名并点击 Generate button

Capgo和CLI将自动提取您的用户名，您不需要记住它。
下载配置文件

点击 Download 按钮下载配置文件

此文件 必须保存 - 您稍后需要它

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

运行配置命令

你已经做到了！你已经准备好配置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

：

Capgo CLI 凭证保存输出

CI/CD 设置（GitHub Actions）

如果您已经完成了 Team ID, Apple 密钥、Apple 密钥 ID 和 Apple 发行者 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

2) 创建仓库密钥

在 GitHub > Repository > Settings > Secrets and variables > Actions, 添加:

密钥名称	值
`CAPGO_TOKEN`	您的 Capgo API token
`APP_STORE_CONNECT_TEAM_ID`	团队 ID 团队 ID
`APPLE_KEY_ID`	密钥 ID Apple 密钥、Apple 密钥 ID 和 Apple 发行者 ID
`APPLE_ISSUER_ID`	发行者 ID Apple key, Apple key ID 和 Apple issuer 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 工作流中使用环境变量

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 }}

构建

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

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

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

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

提交到App Store审查

The normal App Store build path uploads the build to App Store Connect/TestFlight. If your CI release should also attach the processed TestFlight build to the App Store version and submit it for App Review, pass --submit-to-store-review 使用发布构建:

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

This requires App Store Connect API key credentials (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, 和 APP_STORE_CONNECT_TEAM_ID)。App Store Connect专用密码上传和 ad_hoc 发布无法提交构建进行审查。 --store-release-name 是App Store版本，如果省略，Capgo从Xcode项目 MARKETING_VERSION 读取。 --store-release-notes 是App Store What’s New文本的备用文本，每个 --store-release-notes-locale "locale=notes" 条目都可以覆盖它的店铺本地化。使用 --ios-automatic-release to release automatically after Apple approval, or --no-ios-automatic-release to wait for a manual release. --ios-testflight-groups is still available for external beta distribution, but it is not required for App Store review submission.

Ad-Hoc Distribution Mode

By default, Capgo builds iOS apps for App Store distribution (TestFlight + App Store). If you need ad-hoc builds instead (for internal testing or CI artifact collection), you can use the --ios-distribution flag.

何时使用 ad-hoc 模式

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

要求

ad-hoc 构建有 更少的要求 比 App Store 构建更快:

Credential	Required?
Distribution certificate (`.p12`)	Yes
Ad-hoc provisioning profile (`.mobileprovision`)	Yes
Team ID (`--apple-team-id`)	Yes
App Store Connect API key (`.p8`)	No
Apple Key ID / Issuer ID	没有

没有 App Store Connect __CAPGO_KEEP_0__ 密钥时，构建号自增使用时间戳fallback。要抑制警告，请传递","创建 ad-hoc 配置文件

按照相同的步骤进行分发配置文件,但在第五步中选择 Ad Hoc 而不是 App Store:

前往 Apple Developer Profiles
点击 + 按钮
选择 Ad Hoc and click Continue
选择您的应用程序和分发证书
选择您要注册的设备
命名并下载配置文件

保存 ad-hoc 凭据

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 作为构建工件收集起来，请添加 --output-upload:

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

使用临时构建的 CI/CD

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

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

带有扩展的应用程序（多目标签名）

如果您的应用程序包含扩展（共享扩展、小部件、通知服务扩展等），则每个扩展目标都需要自己的签名配置文件。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"

每个 --ios-provisioning-profile 标志映射一个 bundle ID 到其配置文件。 The CLI:

读取每个 mobileprovision 文件
自动从嵌入的 plist 中提取配置文件名称
Base64-编码文件
将所有内容存储为一个 CAPGO_IOS_PROVISIONING_MAP 凭据

从单个配置文件迁移

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

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

这会将您的现有单配置文件凭据转换为新 CAPGO_IOS_PROVISIONING_MAP 格式并删除遗留的密钥（BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

迁移后，使用以下命令添加扩展配置文件（累积合并）： update 终端窗口

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

故障排除

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

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

因为您已经在创建配置文件后启用了一个新功能。旧的配置文件还没有包含新功能。

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

打开本当主机李学页面
请加执行合为一个学生的分配常或一个学生的分配常。
点击 Profiles 本当主机李学页面选项分配常
来源为一个学生的分配常。
请加执衍合为一个学生的分配常或一个学生的分配常。 Edit button
点击 Save button
点击 Download button
重新运行 Capgo 原生构建设置命令使用新下载的配置文件。

这应该解决问题。

其他问题

如果您遇到任何问题，例如Capgo原生构建、配置凭据或构建应用，请不要犹豫通过我们的支持.

继续从iOS构建

如果您正在使用 iOS构建 来规划CI/CD自动化，连接它与 Capgo CI/CD 为Capgo CI/CD中的产品工作流程 Capgo原生构建为Capgo原生构建中的产品工作流程 Capgo 集成为产品工作流程在 Capgo 集成中 CI/CD 集成为 CI/CD 集成的实现细节 GitHub 动作集成为 GitHub 动作集成的实现细节