iOS Builds

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

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

What you will learn

您将学习如何配置 Capgo Native Build 的证书。
You will learn how to configure the certificates for Capgo Native Build

__CAPGO_KEEP_0__ 账户（免费试用即可开始）

A Capgo account (a free trial is enough to get started)
Your app already registered in Capgo (run bunx @capgo/cli@latest app add 有效的 Apple Developer 账户（$99/年）（您必须在 Apple Developer 账户上具有管理员或所有者权限）
What you will learn
Section titled “What you will learn”
Your app must be able to build successfully via Xcode
一个 Capacitor 应用
一个已配置的应用图标。没有图标的应用无法上传到 App Store。

在 Apple 的门户网站中

在 Apple 的门户网站中，确保 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. The certificate will be created automatically. You can see it in the list. Please check the previous step to confirm that you see it.

Now that you have the distribution certificate installed, you can start the build process.

手动构建到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中用于识别应用
3. 你的应用程序的主要语言
然后，点击 next 按钮
如果创建应用程序记录失败，请尝试关闭窗口并尝试再次存档应用程序。
等待上传完成
如果一切顺利，你应该看到以下屏幕
点击 Done 按钮

你可能会本能地认为现在一切都好，并且你可以在 TestFlight 中看到你的应用程序了，但还有一些事情需要完成：

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

让我们从第一个开始：

添加自己到TestFlight

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

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

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

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

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

设置合规信息

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

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

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

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

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

至于第二个，步骤如下：

打开 Info.plist 文件

添加以下密钥：

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

保存文件

安装TestFlight应用并接受邀请

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

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ 从 App Store 下载
TestFlight

应用

在您的 iOS/iPadOS 设备上

接受测试您的应用的邀请
我将跳过如何在您的设备上安装 TestFlight 应用的详细步骤。如果您不确定如何安装应用，请参阅 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 Developer Team ID（在 Apple Developer Portal)
`--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 密钥、Apple 密钥 ID 和 Apple 发行者 ID

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

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

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

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

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

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

这 必须保存 - 之后你会需要它

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

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

证书

现在，你准备好导出证书了。

你还记得本指南的第一步吗？就是设置分发证书。然而，Apple 在他们的无限智慧中，决定导出证书的方式与创建证书的方式有所不同 🙃 让我们继续设置：

打开钥匙串访问
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_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 发行者 ID
`APPLE_ISSUER_ID`	Key ID from Apple key, Apple key ID 和 Apple 发行者 ID
`BUILD_CERTIFICATE_BASE64`	Content of `certificate_base64.txt`
`CAPGO_IOS_PROVISIONING_MAP`	由 CLI 生成 — 从 `.capgo-credentials` 文件
`APPLE_KEY_CONTENT`	Content of `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 版本并提交审核，请传递 --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

这需要 App Store Connect API 密钥凭证（APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT，和 APP_STORE_CONNECT_TEAM_ID）。App 专用密码上传和 ad_hoc 分发无法提交构建进行审查。 --store-release-name 是 App Store 版本；如果省略，Capgo 将 MARKETING_VERSION 从 Xcode 项目中读取。 --store-release-notes 是 App Store What’s New 文本的备用文本，且每个 --store-release-notes-locale "locale=notes" 条目都可以覆盖它以适应不同语言的 App Store。使用 --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 构建:

凭证	是否必需
分布证书（`.p12`)	是
广泛分发配置文件（`.mobileprovision`)	是
团队 ID（`--apple-team-id`)	是
App Store Connect API 密钥（`.p8`)	否
Apple Key ID / 发行者 ID	No

创建一个 ad-hoc 配置文件

按照相同步骤配置文件,但在第 5 步中选择 自定义 而不是 App Store:

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

保存即时任务凭据

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

对于 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 标志映射一个包 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"

配置文件不包含 XYZ 能力。

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

__CAPGO_KEEP_0__

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

因为您在创建分发配置文件后启用了新功能。旧的分发配置文件尚未包含新功能。

要解决此问题，请重新生成分发配置文件。

打开 Apple Developer Portal
在下拉菜单中选择正确的团队
点击 Profiles button
找到您要重新生成的分发配置文件
点击 Edit button
点击 Save button
点击 Download button
重新运行 Capgo 原生构建设置命令使用新下载的配置文件即可解决问题。

其他问题']}

targetLanguage

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

继续从iOS Builds

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