iOS 构建

使用 Capgo 的专用 Mac 基础设施构建 iOS 应用并提交至 TestFlight 和 App Store。

学习内容

• 你将学习如何通过 Capgo Native Build 上传你的 App
• 你将学习如何为 Capgo Native Build 配置证书

前提条件

• 一个 Capgo 账号（免费试用即可开始）
• 你的应用已在 Capgo 中注册（请运行 bunx @capgo/cli@latest app add 如未注册）
• 无需 Mac：Capgo Build 会在云端编译并签名你的 iOS App，因此你可以在 macOS、Windows 或 Linux 上运行
• 有效的 Apple Developer 账号（$99/年）（你必须拥有该 Apple Developer 账号的管理员或所有者权限）
• 你的 App 必须能够成功构建（无论是在本地 Xcode 中，还是使用 Capgo Build）
• 一个 Capacitor App
• 为 App 配置好图标。没有图标的 App 无法上传到 App Store。

注意

在本教程中，我将使用以下 App： https://github.com/Cap-go/capgo-native-build-tutorial-app

在 Apple 门户中开始之前

在配置证书或触发首次 TestFlight 上传之前，请确保 Apple 账号和团队已准备就绪：

• 为用于注册的 Apple Account 开启双重认证
• 选择合适的会员类型：
  • 个人 / 独资企业：你的法定姓名将成为 App Store 上的卖家名称
  • 组织：需要具备法人实体、D-U-N-S 编号、公开的公司网站、公司域名的工作邮箱，以及有权代表组织签署 Apple 协议的人员
• 使用可同时访问 Apple Developer 和 App Store Connect 的账号来管理证书、App 记录、API 密钥以及 TestFlight
• 尽早确定最终的 Bundle ID。后期更改通常意味着需要重新进行 App Store 的配置工作
• 在 App Review 前，请提前准备好 App Store Connect 的这些内容：支持 URL、隐私政策 URL、年龄分级、截图、出口合规性以及 App Review 联系方式

注意

实用的官方参考资料：

• 加入 Apple Developer Program
• 提交您的 App 和游戏
• App Store Connect 中的平台版本信息

注意

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

推荐方案：自动化 onboarding

你无需手动完成这些操作。Capgo 的 onboarding 会为你自动创建并配置 iOS 签名凭据（distribution certificate + provisioning profile）——这是推荐的做法：

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

以下手动操作指南仅适用于希望自行配置凭据，或想深入了解 Capgo 底层机制的用户。

首次手动构建

在开始使用 Capgo 构建应用之前，我们应先完成初始配置，并手动执行一次 TestFlight 构建。 先进行手动构建有一些优势：

• 你将在本地机器上配置分发证书
• 如果你尚未创建 App Store 记录，现在可以创建
• 你将能够排查与你的应用 code 相关的构建流程问题

在开始之前，您必须在本地机器上安装分发证书。 这个过程比较复杂，但下面我会详细解释。

配置分发证书

1. 打开 Xcode

2. 点击 Xcode -> Settings... 或者，你可以使用快捷方式 Cmd + ,

   

3. 前往 Accounts

4. 找到已添加到 Apple 开发者账户的 Apple 账户

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

6. 点击 Manage Certificates... 按钮

7. 确保列表中能看到分发证书

8. 如果没有，您需要创建一个新的证书

   注意

   Apple 限制您拥有的分发证书数量为 3 个。如果您已有超过 3 个证书，需要先删除一个才能创建新的。本教程不会涵盖此操作。

   1. 点击 + 按钮，然后选择 Apple Distribution
   2. 证书将自动创建。您可以在列表中看到它。请查看上一步以确认您能看到该证书。

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

手动构建到 TestFlight

1. 在 Xcode 中打开 App

   运行 bunx cap open ios 以在 Xcode 中打开 App。

2. 找到并点击 archive 按钮

   在 Xcode 工具栏中，找到并点击 product -> archive 按钮。

   

3. 等待构建完成

4. 点击 Distribute App 按钮

   

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

   

6. 配置 App 记录

   填写以下字段：

   1. Name：您的 App 名称 - 会在 App Store 中显示
   2. SKU：您的 App SKU - 用于在 App Store 中识别您的 App
   3. 主要语言：您的 App 的主要语言

   然后，点击 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. 选择创建 App 记录时使用的团队。如果你只属于一个开发者账号，可以跳过此步骤。

4. 点击 Apps 按钮

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

6. 点击 TestFlight 按钮

7. 点击 Internal Testers plus 按钮

8. 创建新分组

   我喜欢把这个群组命名为“internal”。你也可以随意命名。

   

9. 点击 Invite testers 按钮

10. 将自己添加到组中

    在列表中找到自己，并勾选姓名旁的复选框。（可能需要刷新页面才能看到自己） 然后，点击 Add 按钮。

    

11. 确认你已添加到组中

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

    

恭喜 🎉 你已将自己添加到 TestFlight。现在，在配置 Capgo Native Build 之前， 你只需要再完成一件事。

配置合规信息

现在你需要向 Apple 承诺，你的应用没有使用任何非标准（如自定义算法）加密。如果你的应用确实使用了非标准加密，建议阅读 Apple 文档 了解如何处理此问题。 有两种方法可以实现：

1. 你可以在每次构建应用时手动执行此操作。
2. 你可以配置 plist 文件，将此值自动设置为 false.

我们先从第一个开始：

1. 按照上一节的所有步骤，在 App Store Connect 中找到 TestFlight 部分

2. 点击 Builds -> iOS

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

4. 选择最符合你 App 情况的选项

   我的情况是 none，但你的情况可能不同。 然后点击保存

   

5. 你的 App 现在应该显示 ready to test

   

至于第二种情况，步骤如下：

1. 打开 Info.plist 文件

2. 添加以下 key：

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

3. 保存文件

注意

这里 是 Apple 官方文档，介绍如何向 Apple 说明您符合加密出口法规。

安装 TestFlight 应用并接受邀请

现在，您 就快 可以在 TestFlight 中测试您的应用了。 在此之前，您需要完成以下事项：

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

这里不再赘述如何在设备上安装 TestFlight App。如果你不确定怎么安装应用，Google 上有一些很棒的指南。

关于接受邀请：你会收到一封来自 Apple 的邮件，其中包含接受邀请的链接。

1. 打开 Apple 发来的包含接受邀请链接的邮件

2. 点击 View in TestFlight 按钮

3. 点击 Install 按钮

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

   如果你之前用 Xcode 安装过这个 App，可能会看到以下界面。请点击 install 按钮。

5. 等待 App 安装完成

6. 点击 Open 按钮并点击它

恭喜 🎉 你已接受在 TestFlight 中测试 App 的邀请。现在，你可以配置 Capgo Native Build 来构建 App 并提交到 TestFlight。

配置 Capgo Native Build

为了能构建 App 并提交到 TestFlight，你需要在 Capgo Native Build 中配置几项内容。 以下是你需要传给 Capgo CLI 的配置项列表：

参数	描述
--platform	要构建的平台 (ios)
--apple-team-id	您的 Apple Developer Team ID (可在 Apple 开发者门户)
--apple-key	App Store Connect API 密钥文件路径 (.p8 文件)
--apple-key-id	App Store Connect API 密钥的 Key ID
--apple-issuer-id	您的 App Store Connect Issuer ID
--certificate	分发证书路径 (.p12 文件)
--ios-provisioning-profile	Provisioning profile 映射 (bundleId=path 或仅提供单个 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 '/path/to/profile.mobileprovision'

团队 ID

先从 Team ID 开始。找到它很容易。

1. 前往 Apple 开发者账号 并向下滚动

2. 找到 Team ID

   

Apple key、Apple key ID 和 Apple issuer ID

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

macOS：让 Capgo 为您创建此密钥

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

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

   注意

   对我来说，这个链接有时无法正常工作。如果对您也不起作用，请重新加载页面。

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

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

3. 点击 Integrations 按钮

4. 找到 issuer

   注意

   此项 需要保存 - 稍后会用到

   点击 copy 复制 Issuer 的按钮

5. 点击加号按钮

6. 设置 Key 名称并将访问权限设为 App manager 并点击 Generate 按钮

7. 保存 Key ID

   注意

   此项 需要保存 - 稍后会用到

   

8. 下载密钥

   注意

   此项 需要保存 - 稍后会用到

   危险

   切勿将密钥分享给任何人——请仅在 CAPGO CLI 中使用

   

   

恭喜 🎉 您已成功创建 Apple 密钥、Apple key ID 和 Apple issuer ID。

证书

现在，您可以导出证书了。还记得吗，本指南最初的步骤之一就是设置分发证书。

不过，Apple 以他们“无穷的智慧”决定，导出证书的方式与创建时完全不同 🙃 下面开始设置：

1. 打开 Keychain Access

   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 文件完全受 Capgo CLI 支持 - 只需在运行配置命令时使用 --p12-password 选项提供密码即可。

   

7. 当提示输入“登录钥匙串密码”时，请输入你登录 Mac 所用的密码

   输入你登录 Mac 所用的密码。然后点击 Allow 按钮。

   

恭喜 🎉 您已导出证书。

描述文件

现在，您可以导出 provisioning profile 了。我保证，这是您需要从 Apple 获取的最后一项内容。

1. 前往 Apple Developer 描述文件

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

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

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

   

4. 点击 + 按钮

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

   

6. 选择要构建的 App

   在下拉菜单中找到你的 App 并点击 Continue 按钮

   

7. 选择正确的分发证书

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

   

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

   

8. 为配置文件命名

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

   提示

   配置文件名称由 Capgo CLI 自动提取——您无需记住它。

   

9. 下载描述文件

   点击 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

替换占位符值

将上述占位符值替换为前几步中获取的实际凭据：

• --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 分钟的令牌。即使时钟仅相差几秒，也可能导致此步骤失败。

请参阅 builder 故障排除指南 以了解时钟同步步骤。

CI/CD 配置 (GitHub Actions)

如果您已完成 团队 ID, Apple key、Apple key ID 和 Apple issuer 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_TOKEN	你的 Capgo API token
APP_STORE_CONNECT_TEAM_ID	来自 团队 ID
APPLE_KEY_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 只通过环境变量传递凭据。无需提交签名文件，也无需将其作为 workflow artifacts 上传。

运行构建

现在，你可以运行第一次构建了。

运行以下命令来构建你的应用：

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 配合 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_ID）。App 专用密码上传和 ad_hoc 分发无法提交构建以供审核。 --store-release-name 是 App Store 版本；如果省略，Capgo 将从 MARKETING_VERSION Xcode 项目中读取。 --store-release-notes 是 App Store 的“新功能”回退文本，每个 --store-release-notes-locale "locale=notes" 条目都可以为商店本地化覆盖它。使用 --ios-automatic-release 在 Apple 批准后自动发布，或者 --no-ios-automatic-release 以等待手动发布。 --ios-testflight-groups 仍可用于外部 Beta 分发，但提交 App Store 审核时并非必需。

Ad-Hoc 分发模式

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

注意

Ad-hoc 分发 不会 与 Enterprise (In-House) 分发相同。Enterprise 分发需要独立的 Apple Developer Enterprise 账号，并使用不同的 provisioning profiles。Capgo 目前仅支持 app_store 以及 ad_hoc 模式。

何时使用 ad-hoc 模式

• 你想直接向已注册设备分发 IPA（无需使用 TestFlight）
• 你没有或不想使用 App Store Connect API 密钥
• 你想通过以下方式收集构建产物 --output-upload 而无需提交至 App Store

要求

Ad-hoc 构建的要求 少于 App Store 构建：

凭据	是否必填？
分发证书（.p12)	是
Ad-hoc 描述文件 (.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 密钥，构建号自动递增将使用基于时间戳的回退机制。要抑制此警告，请传入 --skip-build-number-bump.

创建 ad-hoc provisioning profile

按照与 描述文件相同的步骤操作，但在第 5 步中，选择 Ad Hoc 分发 而不是 App Store:

1. 前往 Apple Developer 描述文件
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 所需。

运行 ad-hoc build

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

使用 ad-hoc build 实现 CI/CD

相比 App Store 构建，GitHub Actions 需要的 secrets 更少：

.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 构建并非必需。

包含 Extension 的 App（多 Target 签名）

如果你的 App 包含 extension（share extension、widget、notification service extension 等），每个 extension target 都需要单独的 provisioning profile。Capgo 通过可重复的 --ios-provisioning-profile 标志。

示例：App + Share Extension

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 flag 会将 bundle ID 映射到其 provisioning profile 文件。CLI：

1. 读取每个 mobileprovision 文件
2. 从内嵌的 plist 中自动提取 profile 名称
3. 对文件进行 Base64 编码
4. 将所有内容存储为单个 CAPGO_IOS_PROVISIONING_MAP 凭据

提示

所有 target 共用一个 distribution certificate —— 只有 provisioning profile 会因 target 而异。

从单一 Profile 迁移

如果你之前使用过 BUILD_PROVISION_PROFILE_BASE64 （single profile），请运行：

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 从零开始设置所有凭据时使用。

故障排除

Provisioning profile 不包含 XYZ capability。

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

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

这是因为您在创建 Provisioning Profile 之后启用了新的 Capability。 旧的 Provisioning Profile 尚未包含该新 Capability。

要修复此问题，您需要重新生成描述文件。

1. 打开 Apple 开发者门户
2. 在下拉菜单中选择正确的团队
3. 点击 Profiles 按钮
4. 找到您想要重新生成的描述文件
5. 点击 Edit 按钮
6. 点击 Save 按钮
7. 点击 Download 按钮
8. 重新运行 Capgo Native Build 设置命令 并使用新下载的描述文件。

这应该能解决问题。

其他问题

如果由于任何原因，您在 Capgo Native Build、配置凭据或构建应用时遇到问题，请随时通过我们的渠道联系我们。 支持团队.

从 iOS Builds 继续

如果你正在使用 iOS 构建 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成 用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成 用于 Capgo 集成中的产品工作流， CI/CD 集成 了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成 有关 GitHub Actions 集成的实现细节。