iOS Builds

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

你将学到什么

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

前提条件

• 一个 Capgo 帐户（免费试用版足以开始）
• 你的应用已经在 Capgo 注册（如果没有，请运行 bunx @capgo/cli@latest app add if not)
• A Mac computer with Xcode installed (it’s possible to setup the build on a linux/windows machine, but it’s not yet documented)
• 有效的苹果开发者账户（$99/年）(您必须在苹果开发者账户上拥有管理员或拥有者权限)
• 您的应用程序必须能够通过Xcode成功构建
• 一个Capacitor应用
• 应用程序的已配置图标。没有图标的应用程序无法上传到App Store。

注意

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

在苹果门户中

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

• 开启用于注册的Apple Account的两因素认证
• 选择合适的会员类型：
  • 个人/独资企业：您的法定姓名将成为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联系方式

注意

有用官方参考：

• 成为苹果开发者计划的成员
• 提交你的应用和游戏
• App Store Connect中的平台版本信息

注意

苹果定期更新其最低SDK要求。截至 2026年4月28日在App Store Connect中上传的iPhone和iPad应用必须使用 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 Account 的 Apple Account

5. 找到您将用于部署应用的团队

6. 点击 Manage Certificates... 按钮

7. 确保您可以在列表中看到分发证书

8. 如果您没有看到，请创建一个新的证书

   注意

   苹果限制您可以拥有的分发证书数量为 3。如果您有超过 3 个证书，则需要删除一个以便创建一个新的。该教程将不覆盖此内容

   1. 点击 + button and then on Apple Distribution
   2. 证书将自动创建。您可以在列表中看到它。查看上一步以确认您看到它。

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

手动构建到 TestFlight

1. 在 Xcode 中打开应用

   运行 bunx cap open ios 在 Xcode 中打开应用。

2. 找到并点击 archive 按钮

   在 Xcode 工具栏中找到并点击 product -> archive button.

   

3. 等待构建完成

4. 点击 Distribute App button

   

5. 选择 TestFlight Internal Only 作为发布方法并点击 Distribute button

   

6. 配置应用记录

   请填写以下字段：

   1. Name: 应用程序名称 - 在 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. 上下文：解决方案页面应用程序示例部分。角色：短UI标签或导航项。见于：组件解决方案/解决方案应用程序示例.astro。消息键`solution_app_examples_rating` (解决方案应用程序示例等级)。
5. 准备与您实际支持的设备匹配的截图

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

让我们从第一个开始：

1. 标题：加入TestFlight 前往 App Store Connect页面

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

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

4. 点击 Apps 按钮

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

6. 点击 TestFlight 按钮

7. 点击内部测试者按钮 Internal Testers plus 按钮

8. 创建新组

   我喜欢将组命名为“内部”。您可以将其命名为任何您想要的名称。

   

9. 点击 Invite testers 按钮

10. 将自己添加到组中

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

    

11. 验证您已加入组

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

    

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

设置合规信息

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

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应用并接受邀请

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

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

我将跳过如何在您的设备上安装 TestFlight 应用的详细步骤。如果您不确定如何安装应用，请参阅 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 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开始。找到它是相当容易的。

1. 前往 Apple Developer Account and scroll down

2. Find the Team ID

   

Apple key, Apple key ID and Apple issuer ID

Now, let’s move on to the Apple key.

macOS：让 Capgo 为您创建此密钥

在macOS上 capgo build init 可以让 API 为您创建此App Store Connect密钥。 选择 “不 — 为我创建一个” and a guided window opens App Store Connect, walks you through each step, and captures the key, Key ID and Issuer ID automatically — no copy-paste. The manual steps below are the alternative (and the path on Windows or Linux).

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

   注意

   如果链接不起作用，请尝试重新加载页面

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

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

3. 点击 Integrations 按钮

4. 找到 issuer

   注意

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

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

5. App Store Connect 添加密钥按钮

6. 设置密钥名称并设置访问权限 App manager 点击并点击 Generate 按钮

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 文件

   注意

   这 必须保存 - 您将需要它后面

   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 按钮。

   

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

配置文件

配置文件

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

2. Apple Developer Profiles（苹果开发者配置文件）

   1. 点击右上角的你的名字
   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 证书
• --ios-provisioning-profile: 下载的路径 .mobileprovision 文件（bundle ID自动推断为单个配置文件）

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

Apple认证失败？ 同步时钟

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

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

CI/CD设置（GitHub Actions）

如果您已经完成 团队 ID, Apple key、Apple key ID 和 Apple 发行者 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.

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_TOKEN	您的 Capgo API token
APP_STORE_CONNECT_TEAM_ID	团队 ID 团队 ID
APPLE_KEY_ID	密钥 ID Apple Key、Apple Key ID 和 Apple Issuer ID
APPLE_ISSUER_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 工作流中使用环境变量

/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 版本并提交到 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

这需要 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 会从 Xcode 项目中读取。 MARKETING_VERSION App Store 评审 --store-release-notes 是 App Store 的 fallback What’s New 文本，每个 --store-release-notes-locale "locale=notes" 条目可以覆盖它以适应店铺的本地化。使用 --ios-automatic-release 来自动发布苹果批准后，或者 --no-ios-automatic-release 等待手动发布。 --ios-testflight-groups 仍然可用于外部 beta 分发，但它不是 App Store 评审提交所必需的。

内部测试或 CI artifact 收集所需的 ad-hoc 构建

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

内部测试或 CI artifact 收集所需的 ad-hoc 分发是

内部测试或 CI artifact 收集所需的 ad-hoc 分发方式 Not the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. __CAPGO_KEEP_0__ currently supports 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 When to use ad-hoc mode

使用 ad-hoc 模式的时机

• 您想直接将 IPA 分发给已注册的设备（不使用 TestFlight）
• You don’t have or don’t want to use an App Store Connect API key
• 您没有或不想使用 App Store Connect __CAPGO_KEEP_0__ 密钥 --output-upload You want to collect build artifacts via

您想通过

App Store 内部构建比外部构建有 外部构建比 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.

创建一个 ad-hoc 配置文件

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

1. 前往 Apple Developer 配置文件
2. 点击 + button
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 needed.

进行 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 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 不需要用于 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:

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 标题：故障排除

配置文件不包含 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. 点击 Edit 按钮
6. 点击 Save 按钮
7. 点击 Download 按钮
8. 重新运行 Capgo 原生构建设置命令 使用刚下载的资料

这应该解决问题。

其他问题

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

继续从iOS Builds

如果您正在使用 iOS Builds 来规划CI/CD自动化，连接它与 Capgo CI/CD Capgo CI/CD Capgo 原生构建 for the product workflow in Capgo 原生构建, Capgo 集成 for the product workflow in Capgo 集成, CI/CD 集成 for the implementation detail in CI/CD 集成, and GitHub 动作集成 for the implementation detail in GitHub 动作集成.