iOS构建

安装

使用 Capgo 专属 Mac 设施，通过 TestFlight 和 App Store 提交 iOS 应用。

您将学到什么

您将学习如何通过 Capgo 原生构建上传您的应用
您将学习如何配置证书来支持Capgo原生构建

Prerequisites

一个Capgo账户（免费试用即可开始）
一个 Capgo 账户（免费试用即可开始） bunx @capgo/cli@latest app add 如果不是)
如果您的应用尚未在 Capgo 注册，请运行此命令注册）
需有有效的Apple Developer账户（$99/年）（您必须在Apple Developer账户上具有管理员或拥有者权限）
您的应用程序必须能够成功构建（在Xcode本地环境中，或使用Capgo Build）
一个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帐户
找到您将用于部署应用的团队
点击 Manage Certificates... 按钮
确保您可以在列表中看到分发证书
如果您无法看到，请创建新的证书

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

现在您已经安装了分发证书，可以开始构建过程了。

手动构建到TestFlight

在Xcode中打开应用

运行 bunx cap open ios 为了打开应用在Xcode中，
找到并点击 archive 按钮

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

填写以下字段:
1. 名称：您的应用名称 - 在 App Store 中可见
2. SKU - 应用程序的 SKU - 这是用于在 App Store 中识别您的应用程序的 SKU
3. 主语言 - 应用程序的主语言
然后，点击 next 按钮
如果创建应用程序记录失败，请尝试关闭窗口并尝试再次存档应用程序。
等待上传完成
如果一切顺利，您应该看到以下屏幕
点击 Done 按钮

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

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

让我们从第一步开始：

加入 TestFlight

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

我喜欢将组命名为“内部”。您可以将其命名为任何您想要的名称。
点击 Invite testers button
将自己添加到组中

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

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

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

设置合规信息

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

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

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

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

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

至于第二个，以下是步骤：

打开文件 Info.plist 文件

添加以下键:

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

保存文件

安装TestFlight应用程序并接受邀请

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

下载 TestFlight 应用从 App Store 上的 iOS/iPadOS 设备上
接受测试您的应用的邀请

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

关于接受邀请，您将收到来自 Apple 的一封邮件，包含接受邀请的链接。

打开来自 Apple 的邮件，包含接受邀请的链接
点击 View in TestFlight 按钮
点击右键 Install 按钮
在您的设备上安装应用

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

恭喜！您已接受测试飞行的邀请。现在，您可以配置Capgo原生构建来构建并将应用提交到测试飞行。

配置Capgo原生构建

您需要配置以下几项才能在Capgo原生构建中构建和提交您的应用到TestFlight。以下是您将传递给Capgo CLI的列表:

参数	描述
`--platform`	要构建的平台（`ios`)
`--apple-team-id`	您的Apple Developer Team ID（在 Apple Developer Portal)
`--apple-key`	您的App Store ConnectAPI Key文件路径（`.p8` 文件）
`--apple-key-id`	您的App Store ConnectAPI Key的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 开始。找到它很容易。

前往苹果开发者账户并滚动到底部
找到 Team ID

Apple key、Apple key ID 和 Apple issuer ID

现在，让我们继续到 Apple key。

前往 App Store Connect 登录页面

如果链接不工作，请尝试重新加载页面
选择正确的团队
1. 点击右上角的用户名
2. 选择要使用的团队
点击 Integrations 按钮
找到 issuer

此 请保存 您将需要它

点击复制发行者 copy App Store Connect 复制发行者
App Store Connect 添加密钥按钮
并点击 App manager 按钮 Generate button
保存密钥 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 文件完全支持__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - 只需在运行配置命令时使用
当被要求输入“登录密钥链密码”，请输入您用于登录 Mac 的密码

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

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

配置文件

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

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

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

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

如果您不确定要选择哪个证书，请返回 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）

如果你已经完成了团队ID, Apple ID, Apple 密钥 ID 和 Apple 发行者 ID, 证书, 和配置文件您已经具备了CI/CD所需的所有内容。\n本节仅介绍如何将这些值作为GitHub Actions机密和环境变量传递。

页面路径: /zh/docs/builder/ios/

# 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 密钥、Apple 密钥 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 工作流中使用环境变量

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审查

正常的 App Store 构建路径将构建上传到 App Store Connect/TestFlight。如果您希望 CI 发布附带处理的 TestFlight 构建并将其提交到 App Store 版本进行 App Review，请传递 --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, and APP_STORE_CONNECT_TEAM_ID分发无法提交构建进行审查。 ad_hoc 是 App Store 版本；如果省略，__CAPGO_KEEP_0__ 将从 Xcode 项目中读取。 --store-release-name 是 App Store 版本；如果省略，Capgo 会读取 MARKETING_VERSION 个 --store-release-notes 项 --store-release-notes-locale "locale=notes" 可以覆盖它以实现商店本地化。使用 --ios-automatic-release 以苹果审批后自动发布，或者 --no-ios-automatic-release 等待手动发布。 --ios-testflight-groups 仍然可用于外部beta分发，但它并不是App Store审查提交所必需的。

内部测试或CI artifact收集的目的而不是App Store发布的

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

何时使用ad-hoc模式

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

要求

ad-hoc构建有 比 App Store 构建少的要求： 而 App Store 构建：

凭证	是否需要？
分发证书（`.p12`)	是
上下文：Capgo 解决方案营销页面。角色：短 UI 标签或导航项。见于：页面 solutions/beta-testing.astro。消息键 `solutions_beta_testing_compare_native_tf` (解决方案 Beta 测试比较原生 Tf)。 \| 上下文：Capgo 解决方案营销页面。角色：短 UI 标签或导航项。见于：页面 solutions/pr-preview.astro。消息键 `solutions_pr_compare_native_tf` (解决方案 Pr 比较原生 Tf)。`.mobileprovision`)	是
自助服务配置文件（`--apple-team-id`)	是
App Store Connect API 密钥 (`.p8`)	No
Apple Key ID / Issuer ID	没有

创建一个 ad-hoc 配置文件

按照相同的步骤配置文件在第五步中选择 应用程序 而不是 App Store:

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

保存 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 需要.

运行一个 ad-hoc 构建

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

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

如果您的应用程序包含扩展（共享扩展、小部件、通知服务扩展等），则每个扩展目标都需要自己的签名文件。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 到其配置文件。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 按钮
找到您要重新生成的配置文件
点击 Apple Developer Edit 按钮
点击 Apple Developer Save 按钮
点击 Apple Developer Download 按钮
重新运行 Capgo 原生构建设置命令使用刚下载的配置文件

这应该解决问题

其他问题

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

继续从iOS Builds

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

iOS构建

您将学到什么

Prerequisites

在Apple的门户网站中

第一个手动构建

设置分发证书

手动构建到TestFlight

加入 TestFlight

设置合规信息

安装TestFlight应用程序并接受邀请

配置Capgo原生构建

团队 ID

Apple key、Apple key ID 和 Apple issuer ID

证书

配置文件

运行配置命令

CI/CD设置（GitHub Actions）

页面路径: /zh/docs/builder/ios/

2) 创建仓库密钥

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

运行构建

提交到App Store审查

内部测试或CI artifact收集的目的而不是App Store发布的

何时使用ad-hoc模式

要求

创建一个 ad-hoc 配置文件

保存 ad-hoc 凭据

运行一个 ad-hoc 构建

CI/CD 与 ad-hoc 构建

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

示例：应用程序 + 共享扩展

从单一配置文件迁移

故障排除

故障排除

其他问题

继续从iOS Builds