iOS Builds

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

你将学到什么

• 你将学习如何通过 Capgo 原生构建上传你的应用程序
• 你将学习如何配置 Capgo 原生构建的证书

前提条件

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

注意

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

在苹果门户中开始之前

在设置证书或触发首次TestFlight上传之前，请确保苹果账户和团队准备好:

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

注意

有用的官方参考：

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

注意

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

建议：自动注册

您不需要亲自处理这些步骤。Capgo的注册功能会为您创建和配置iOS签名凭证（分发证书+配置文件）— 这是推荐的路径:

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

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

第一个手动构建

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

• 您将在本地机器上设置分发证书
• 您将创建应用商店记录，如果您尚未完成
• 您将能够解决与应用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 按钮

   

3. 等待构建完成

4. 点击 Distribute App 按钮

   

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

   

6. 配置应用记录

   填写以下字段:

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

   然后，点击 next 按钮

   

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

8. 等待上传完成

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

10. 点击 Done 按钮

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

1. 加入 TestFlight
2. 完成出口遵从性，以便构建可测试
3. 填写 App Store Connect 必填元数据，如您的支持 URL、隐私政策 URL 和年龄等级
4. context
5. 页面/区域: 解决方案页面应用示例部分。角色: 短 UI 标签或导航项。见于: 组件解决方案/解决方案应用示例.astro。消息键 `solution_app_examples_rating` (解决方案应用示例等级).

准备匹配您实际支持的设备的截图

在生产提交之前添加 App Review 联系信息和任何测试凭证

1. 将自己添加到 TestFlight 标题：将自己添加到 TestFlight 前往

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

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

4. 点击 Apps 按钮

5. 在上一步中创建的应用中找到并点击它

6. 点击 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. 按照上一节的步骤，找到 App Store Connect 中的 TestFlight 部分

2. 点击 Builds -> iOS

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

4. 选择描述您的应用的选项

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

   

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

   

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

1. 打开 Info.plist 文件

2. 添加以下键值对:

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

3. 保存文件

注意

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

安装TestFlight应用并接受邀请

Section titled “Installing the TestFlight app and accepting the invitation” 即将 准备好测试您的应用程序了。测试Flight之前，您需要完成以下步骤：

1. 下载 测试Flight应用 从您的iOS/iPadOS设备上App Store下载
2. 接受测试您的应用程序的邀请

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

接受邀请的具体步骤是，您将收到来自Apple的电子邮件，包含接受邀请的链接。

1. 打开来自Apple的电子邮件，包含接受邀请的链接

2. 点击 View in TestFlight 按钮

3. 点击测试飞行按钮 Install 按钮

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

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

5. 等待应用安装

6. 点击 Open 按钮并点击

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

配置Capgo原生构建

为了能够构建并将应用程序提交到 TestFlight，您需要在Capgo原生构建中配置一些内容。 以下是您将传递给Capgo CLI的内容列表:

参数	描述
--platform	要构建的平台（ios)
--apple-team-id	您的 Apple 开发者团队 ID（在 Apple 开发者门户)
--apple-key	您的 App Store Connect API Key 文件路径（.p8 文件)
--apple-key-id	您的 App Store Connect API 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 开始。找到它很容易。

1. 前往 苹果开发者账户 并滚动到底部

2. 找到 Team ID

   

Apple key、Apple key ID 和 Apple issuer ID

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

macOS：让 Capgo 为您创建此密钥

在 macOS 上 capgo build init 可以让 API 为您创建 App Store Connect 密钥。 选择 “不 — 为我创建一个” 并打开一个引导式窗口，App Store Connect 将您带到每一步，并自动捕获密钥、Key ID 和 Issuer ID — 无需复制粘贴。以下是手动步骤（Windows 或 Linux 上的路径）

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

   注意

   如果链接有时无法工作，请尝试重新加载页面

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

   1. 点击右上角的用户名
   2. 选择要使用的团队

3. 点击 Integrations 按钮

4. 找到 issuer

   注意

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

   点击复制 copy App Store Connect 复制发行者

5. App Store Connect 添加密钥

6. 并点击 App manager button to copy the issuer Generate button

7. 保存密钥 ID

   注意

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

   

8. 下载密钥

   注意

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

   危险

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

   

   

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

证书

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

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

1. 打开钥匙串访问

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

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

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

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

4. 右键单击证书并选择 Export

5. 以文件形式保存证书 .p12 注意

   这

   必须保存 - 您稍后会需要它 在Keychain Access中查找证书

   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 文件完全支持__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - 只需在运行配置命令时使用

   

7. 当被要求输入“登录密钥链密码”，请输入您用于登录 Mac 的密码

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

   

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

配置文件

Page/area: Capgo Builder / native cloud build product page. Role: Short UI label or navigation item. Seen in: page native-build.astro. Message key `native_build_v2_wiz_ios_s3_l` (Native Build V2 Wiz Ios S3 L).

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

2. 前往

   1. Apple Developer Profiles（苹果开发者配置文件）
   2. 点击您要使用的团队

3. 确保您在正确的页面 它应该看起来像这样，如果不这样，请点击 profiles 在侧边栏中

   

4. 点击 + 按钮

5. 选择配置文件类型 选择 App Store Connect 并点击 Continue 按钮

   

6. 选择您要构建的应用

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

   

7. 选择正确的分发证书

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

   

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

   

8. 命名配置文件

   为配置文件命名并点击 Generate 按钮

   提示

   配置文件名会自动从Capgo CLI中提取 — 您不需要记住它。

   

9. 下载配置文件

   点击下载 Download 按钮下载配置文件

   注意

   此文件 应保存 - 您将需要它稍后

   

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

注意

请勿将您刚刚创建的凭据提交到您的仓库。 请妥善保管它们！ 🔒

配置命令的说明

您已经成功了！您现在已经准备好配置 Capgo 原生构建了。

您需要运行的命令是：

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 团队 ID
• --apple-key: 下载的文件路径 .p8 密钥文件
• --apple-key-id: 您的 Apple 密钥 ID
• --apple-issuer-id: 您的 Apple 发行商 ID
• --certificate: 导出的证书路径 .p12 : 导出的文件路径 (单个配置文件时自动推断 bundle ID)
• --ios-provisioning-profile: 下载的文件路径 (bundle ID 自动推断) .mobileprovision : 导出的证书路径

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

Apple认证失败？同步时钟

如果App Store Connect API 密钥看起来正确，但认证仍然失败，请同步计算机时钟并重试。 Capgo 使用本地系统时间签名Apple的JWT，如果Apple拒绝超过20分钟未来的令牌，仅仅几秒钟的时钟不准确就足以使这一步骤失败。

查看 构建器故障排除指南 同步时钟的步骤。

CI/CD设置（GitHub Actions）

如果你已经完成了 团队ID, Apple key, Apple key ID and Apple issuer ID, 证书, 和 配置文件, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

, 您已经具备了 CI/CD 所需的所有内容。 本节仅介绍如何将这些值作为 __CAPGO_KEEP_0__ Actions 秘密和环境变量传递。

# 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 secrets should be single-line values. tr -d '\n' 去除 base64 输出中的换行符。

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 颁发者 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。

提交到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-specific password uploads and APP_STORE_CONNECT_TEAM_ID分发不能提交一个 build 进入 review. ad_hoc 是 App Store 版本；如果省略，__CAPGO_KEEP_0__ 从 Xcode 项目中读取 --store-release-name is the App Store version; if omitted, Capgo reads MARKETING_VERSION 每个 --store-release-notes fallback App Store What’s New 文本， --store-release-notes-locale "locale=notes" 可以覆盖它以实现商店本地化。 --ios-automatic-release 要在苹果审批后自动发布，或者 --no-ios-automatic-release 等待手动发布。 --ios-testflight-groups 虽然外部 beta 分发仍然可用，但它并非 App Store 审核提交所必需。

内部测试或 CI 工件收集所需的 Ad-Hoc 分发模式

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

ad-hoc 分发是

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

何时使用ad-hoc模式

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

要求

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

凭证	是否需要？
分发证书（.p12)	是
广泛分发配置文件（.mobileprovision)	是
团队 ID（--apple-team-id)	是
App Store Connect API 密钥（.p8)	否
Apple Key ID / Issuer ID	没有

注意

在 ad_hoc 模式下， --apple-key, --apple-key-id，和 --apple-issuer-id 不受支持且被忽略。 这是为什么上面两个App Store Connect行没有显示 ad-hoc CLI 标志的原因；这些选项仅适用于 app_store 模式下。

警告

没有 App Store Connect API 密钥时，构建号自动递增使用时间戳fallback。要抑制警告，请传递 --skip-build-number-bump.

创建一个临时配置文件

按照相同的步骤 配置文件但是，在第五步中选择 临时配置 而不是 应用商店:

1. 前往 苹果开发者配置文件
2. 点击 + 按钮
3. 选择 Ad Hoc 并点击继续
4. 选择您的应用程序和分发证书
5. 选择您要注册的设备
6. 命名并下载配置文件

保存 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 构建少一些密钥：

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"

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

1. 读取每个 mobileprovision 文件
2. 自动从嵌入的 plist 中提取配置文件名称
3. 将文件进行 Base64 编码
4. 将所有内容存储为一个 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"

提示

使用 update (不 save)添加配置文件到现有的凭据。命令合并新的配置文件与现有的配置文件。使用 update 仅在从头设置所有凭据时使用。 save 故障排除

区域/页面: 支持/高级支持页面或底部支持部分。角色: 小节或页面标题。见于: 页面 support-policy.astro。消息键 `support_policy_troubleshooting_title` (支持政策故障排除标题)。

配置文件不包含 XYZ 能力。

配置文件不包含 XYZ 能力。

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

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

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

1. 打开 苹果开发者门户
2. 在下拉菜单中选择正确的团队
3. 点击 Profiles 按钮
4. 找到您要重新生成的配置文件
5. 点击 Apple Developer 编辑配置 Edit 按钮
6. 点击 Save 按钮
7. 点击 Download 按钮
8. 重新运行 Capgo 原生构建设置命令 使用新下载的配置文件

这应该解决问题

其他问题

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

继续从iOS构建

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