iOS 构建

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

你将学到什么

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

前提条件

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

注意

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

在苹果门户中开始之前

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

• 为用于注册的 Apple 帐户启用两因素身份验证
• 选择正确的会员类型：
  • 个人/独资：您的法律个人姓名将成为 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 联系方式

注意

有用的官方参考资料：

• 成为 Apple Developer Program 的成员
• 提交您的应用和游戏
• App Store Connect 中的平台版本信息

注意

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

推荐：自动注册

您不需要自己处理这些。 Capgo 的注册创建并配置您的 iOS 签名凭证（分发证书 + 配置文件）— 这是推荐的路径：

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

以下手动步骤仅适用于那些愿意自己设置凭据或想了解 Capgo 在幕后做了什么的人。

第一个手动构建

在我们开始使用 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 按钮。

   

3. 等待构建完成

4. 点击 Distribute App 按钮

   

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

   

6. 配置应用记录

   填写以下字段：

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

   然后，点击 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 按钮

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

6. 点击 TestFlight button

7. 点击 Internal Testers plus button

8. 创建一个新的组

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

   

9. 点击 Invite testers 按钮

10. 添加自己到群组

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

    

11. 验证您已添加到群组

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

    

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

设置合规信息

现在您需要向苹果公司保证您的应用程序不使用任何非标准（如自定义算法）加密。如果您的应用程序确实使用任何非标准加密，我建议阅读 苹果文档 关于如何处理此问题。

1. 有两种方法可以做到这一点：
2. 您可以每次构建应用程序时手动完成此操作。 false.

您可以配置您的plist文件，以自动设置此值为

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

2. 遵循上一节中的所有步骤，找到App Store Connect中的TestFlight部分 Builds -> iOS

3. App Store Connect构建iOS按钮 Manage

4. 选择最适合你的应用的选项

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

   

5. 你的应用现在应该说 ready to test

   

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

1. 打开 Info.plist 文件

2. 添加以下键值对：

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

3. 保存文件

注意

这里 请参阅苹果官方文档，了解如何告知苹果您遵守加密出口管制规定。

安装TestFlight应用并接受邀请

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

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

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

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

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

2. 点击 View in TestFlight 测试邀请按钮

3. 测试安装按钮 Install 在您的设备上安装应用

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

   If you have installed the app previously using Xcode, you may see the following screen. Please click on the install button.

5. 等待应用安装

6. 点击 Open 按钮并点击它

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

配置 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. 前往 Apple 开发者账户 并滚动到底部

2. 在开发者账户中找到 Team ID

   

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

Apple key, Apple key ID 和 Apple 发行者 ID

macOS：让Capgo为您创建此密钥

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

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

   注意

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

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

   1. 点击右上角的你的名字
   2. 点击你要使用的团队

3. 点击 Integrations 按钮

4. 找到 issuer

   注意

   这是 需要保存 - 你将需要它

   点击 copy button to copy the issuer

5. 点击

6. App Store Connect添加密钥按钮 App manager 设置密钥的名称并设置访问权限 Generate 和点击

7. App Store Connect添加密钥名称，设置访问权限到应用管理器并生成

   注意事项

   这个 __CAPGO_KEEP_0__ - 您稍后会需要它

   

8. 下载密钥

   注意

   这个 __CAPGO_KEEP_0__ - 您稍后会需要它

   危险

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

   

   

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

证书

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

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

1. 打开Keychain Access

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

2. 选择 login 类别并点击 My Certificates Keychain Access登录类别

3. 证书应该命名为

   Keychain Access找到证书 Apple Distribution: [Your Name/Company] (your team ID)

4. Keychain Access导出证书 Export

5. 保存证书为 .p12 文件

   注意

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

   1. 确保选择证书文件的好名字
   2. 确保文件格式设置为 Personal Information Exchange (.p12)
   3. 点击 Save 按钮

   

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

   • 跳过密码（推荐简化）：点击 OK 不输入密码
   • 设置密码：如果您希望保护证书密码，则可以在此处设置一个。使用密码保护的 .p12 文件完全支持Capgo CLI - 只需在运行配置命令时使用 --p12-password 钥匙串访问保存证书密码对话框

   

7. 输入您用于登录Mac的密码。然后，点击

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

   

Congratulations 🎉 You have exported the certificate.

__CAPGO_KEEP_0__

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

1. 前往 Apple Developer 配置文件

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

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

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

   

4. 点击 + 按钮

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

   

6. 选择要构建的应用

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

   

7. 选择正确的分发证书

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

   

   如果您不确定要选择哪个证书，请返回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 原生构建所需的所有内容。

注意

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

运行配置命令

您已经成功了！您现在已经具备了配置 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 key file
• --apple-key-id: 你的 Apple Key ID
• --apple-issuer-id: 你的 Apple Issuer ID
• --certificate: 导出的 .p12 证书
• --ios-provisioning-profile: 下载的 .mobileprovision 文件 (bundle ID 自动推断为单个配置文件)

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

App Store Connect __CAPGO_KEEP_0__ 密钥看起来正确，但认证仍失败？ 同步您的时钟

如果 App Store Connect API 密钥看起来正确但认证仍失败，请同步您的计算机时钟并重试。 Capgo 使用本地系统时间签名 Apple 的 JWT，Apple 将拒绝过期时间超过 20 分钟的令牌。 只需几秒钟的时钟不一致即可导致此步骤失败。

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

CI/CD 设置 (GitHub Actions)

如果您已经完成了 团队 ID, Apple Key、Apple Key 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

提示

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

2) 创建存储库秘密

在 GitHub > Repository > Settings > Secrets and variables > Actions，添加：

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 秘钥	值
CAPGO_TOKEN	您的 Capgo API token
APP_STORE_CONNECT_TEAM_ID	团队 ID 团队 ID
APPLE_KEY_ID	密钥 ID Apple 密钥、Apple 密钥 ID 和 Apple 发行者 ID
APPLE_ISSUER_ID	Apple 发行者 ID Apple 密钥、Apple 密钥 ID 和 Apple 发行者 ID
BUILD_CERTIFICATE_BASE64	内容 certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	CLI 生成的 — 从 __CAPGO_KEEP_1__ 复制 .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 审核

正常的 App Store 构建路径会将构建上传到 App Store Connect/TestFlight。如果您的 CI 发布应该附加处理的 TestFlight 构建到 App Store 版本并提交审核，请传递 --submit-to-store-review with a release build：

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_IDApp 专用密码上传和 ad_hoc 分发无法提交一个 build 进入审查。 --store-release-name 是 App Store 版本；如果省略，Capgo 从 Xcode 项目中读取。 MARKETING_VERSION 是 fallback App Store What’s New 文本，且每个 --store-release-notes 条目可以覆盖它的 App Store 本地化。使用 --store-release-notes-locale "locale=notes" 来自动在 Apple 批准后发布，或者 --ios-automatic-release 等待手动发布。 --no-ios-automatic-release 仍然可用于外部 beta 分发，但它并不是 App Store 审核提交所必需的。 --ios-testflight-groups Ad-Hoc 分发模式

targetLanguage

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

注意

非预期分布与企业（内部）分布不同。企业分布需要单独的 Apple Developer Enterprise 账户，并使用不同的分发配置文件。__CAPGO_KEEP_0__ 目前支持 和 the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store 何时使用 ad-hoc 模式 ad_hoc “何时使用 ad-hoc 模式”

“非预期分布模式”

• You want to distribute IPAs directly to registered devices (no TestFlight)
• You don’t have or don’t want to use an App Store Connect API key
• You want to collect build artifacts via --output-upload without submitting to the App Store

Requirements

Ad-hoc builds have fewer requirements than App Store builds:

Credential	Required?
istribution certificate (.p12)	是
临时配置文件（.mobileprovision)	是
Team 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.

创建一个ad-hoc配置文件

跟 配置文件,但在第五步中选择 即时配置 而不是 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

对于 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"

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

1. Copy to clipboard
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 command 合并新配置文件与现有配置文件。使用 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. button Save button
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 继续从iOS Builds.

supportUrl

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