跳过内容

iOS 构建

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

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

在苹果门户开始之前

标题:在苹果门户开始之前

在设置证书或触发首次 TestFlight 上传之前,确保 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联系方式
开始Apple Developer入会 继续在网上完成Apple入会流程 选择正确的Apple Developer实体类型 App Store Connect注册后

第一个手动构建

标题:第一个手动构建

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

  • 您将在本地机器上设置分发证书
  • 您将创建应用商店记录,如果您尚未完成则创建
  • 您将能够找出与应用 code 相关的构建过程中的任何问题

在我们开始之前,您必须在本地机器上安装分发证书。 这很复杂,但我将在下面解释.

设置分发证书

标题:设置分发证书
  1. 打开Xcode

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

    Xcode设置

  3. 转到 Accounts Xcode帐户选项卡

  4. 找到已添加到Apple Developer帐户的Apple帐户 Xcode选择的Apple帐户

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

  6. 点击 Manage Certificates... 按钮 Xcode管理证书

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

  8. 如果您无法看到,请创建新的证书

    1. 点击 + 按钮,然后点击 Apple Distribution Xcode 添加证书
    2. 证书将自动创建。您可以在列表中看到它。查看上一步以确认您看到它。

现在您已经安装了分发证书,可以开始构建过程了。

手动构建到 TestFlight

手动构建到TestFlight
  1. 在Xcode中打开应用

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

  2. 找到并点击 archive 按钮

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

    Xcode工具栏

  3. 等待构建完成

  4. 点击 Distribute App 按钮

    Xcode 分发按钮

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

    Xcode TestFlight 内部仅限分发方法

  6. 配置应用记录

    填写以下字段:

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

    然后,点击 next 按钮

    Xcode TestFlight 配置 app 记录

  7. 如果创建 app 记录失败,请尝试关闭窗口并再次存档 app。

  8. 等待上传完成

  9. 如果一切顺利,您应该看到以下屏幕 Xcode TestFlight 上传完成

  10. 点击 Done 按钮

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

  1. 将自己添加到 TestFlight 中
  2. 完成出口遵从性,以便构建成为可测试的
  3. 填写 App Store Connect 必填元数据,如支持 URL、隐私政策 URL 和年龄等级
  4. 准备与您实际支持的设备匹配的截图
  5. 在提交生产版本之前,添加App Review联系信息和任何测试凭证

让我们从第一个开始:

添加自己到TestFlight

标题:添加自己到TestFlight
  1. 前往 App Store Connect 页面 App Store Connect登录页面

  2. 使用Apple Developer帐户登录

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

  4. 点击 Apps button App Store Connect apps

  5. 在上一步中创建的应用中找到并点击它 App Store Connect app selection

  6. 点击 TestFlight button App Store Connect testflight

  7. 点击 Internal Testers plus button App Store Connect internal testers plus

  8. 创建一个新组

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

    App Store Connect创建新组

  9. 点击 Invite testers 按钮 App Store Connect邀请测试者按钮

  10. 添加自己到组

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

    App Store Connect邀请测试者复选框

  11. 验证你已经添加到组

    现在,你应该在组中看到自己

    App Store Connect验证测试者

恭喜 🎉 你已经添加自己到TestFlight。现在,还有最后一步 你需要做才能配置Capgo Native Build。

设置应用程序的合规信息

标题:设置应用程序的合规信息

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

  1. 您可以每次构建应用程序时都手动完成此操作。
  2. 您可以配置您的 plist 文件,以自动将此值设置为 false.

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

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

  2. 点击 Builds -> iOS App Store Connect 构建 iOS 按钮

  3. 找到缺少合规信息的构建并点击 Manage App Store Connect管理构建

  4. 选择最能描述你的应用程序的选项

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

    App Store Connect保存合规信息

  5. 你的应用程序现在应该显示 ready to test

    App Store Connect准备测试

至于第二个,以下是步骤:

  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 TestFlight 邀请按钮 点击

  3. TestFlight 安装按钮 Install 在你的设备上安装应用 If you are not sure how to install an app, Google has some great guides on how to do it.

  4. Open the email from Apple with the link to accept the invitation.

    如果您以前使用 Xcode 安装了该应用程序,则可能会看到以下屏幕。请单击 install 按钮。 TestFlight 安装应用程序

  5. 等待应用程序安装

  6. 单击 Open 按钮并单击它

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

要能够构建和提交应用程序到 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。找到它很容易.

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

  2. 找到 Team ID

    开发者账户中的

现在,让我们继续到苹果密钥。

  1. 并且一个引导式窗口打开App Store Connect,带您走过每一步,并自动捕获密钥、Key ID和Issuer ID——无需复制粘贴。以下的手动步骤是替代方案(以及Windows或Linux上的路径)。 前往

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

    1. 点击右上角的你的名字
    2. 点击你要使用的团队 Apple Developer keys团队选择
  3. 点击上面 Integrations 按钮 App Store Connect集成按钮

  4. 找到 issuer

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

  5. 点击加号按钮 App Store Connect 添加密钥按钮

  6. 设置密钥名称并设置访问权限 App manager 并点击 Generate 按钮 App Store Connect 添加密钥名称,设置访问权限到应用管理器并生成按钮

  7. 保存密钥ID

    App Store Connect 复制密钥 ID

  8. 下载密钥

    App Store Connect下载密钥

    App Store Connect下载密钥警告

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

证书

证书

现在,你准备好导出证书了。回想一下,这个指南的第一步是设置分布式证书。

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

  1. 打开钥匙串访问

    1. 点击 Command + Space 打开搜索栏
    2. 在搜索框中输入 Keychain Access
    3. 点击 Keychain Access 应用
  2. 选择 login 类别并点击 My Certificates 按钮 Keychain Access 登录类别

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

    证书应该命名为 Apple Distribution: [Your Name/Company] (your team ID) 在 Keychain Access 中查找证书

  4. 右键点击证书并选择 Export 钥匙串访问导出证书

  5. 将证书保存为 .p12 文件

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

    Keychain Access 保存证书对话框

  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. Keychain Access 保存证书密码对话框

    当被要求输入“登录密钥链密码”时,请输入您用来登录Mac的密码 Allow 输入您用来登录Mac的密码。然后,点击

    按钮。

恭喜你 🎉 你已经导出了证书。

配置文件

配置文件

现在,你已经准备好导出配置文件了。相信我,这是你从苹果那里需要做的最后一件事。

  1. 前往 苹果开发者配置文件

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

    1. 点击右上角的你的名字
    2. 点击你要使用的团队 苹果开发者密钥团队选择
  3. 确保你在正确的页面 如果不是,请点击 profiles 在侧边栏

    Apple Developer profiles页面

  4. 点击 + 按钮 Apple Developer添加配置文件按钮

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

    Apple Developer选择配置文件类型

  6. 选择您要构建的应用

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

    Apple Developer选择应用

  7. 选择正确的分发证书

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

    Apple Developer 选择分发证书

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

    Apple Developer 选择分发证书有效期

  8. 命名配置文件

    为配置文件命名并点击 Generate button

    苹果开发者名称资料

  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

标题:CI/CD 设置 (__CAPGO_KEEP_0__ Actions)

Capgo CLI

If you already completed, you can skip this section. 团队 ID, Apple key, Apple key ID and Apple issuer ID, 证书, 和 配置文件, 你已经具备了 CI/CD 所需的所有内容。 本节仅介绍如何将这些值作为 GitHub Actions 秘密和环境变量传递。 1) 将凭据文件转换为单行 base64

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) 创建仓库秘密

标题:2) 创建仓库秘密

GitHub > Repository > Settings > Secrets and variables > Actions,添加:

秘密名称
CAPGO_TOKEN您的 Capgo API token
APP_STORE_CONNECT_TEAM_ID团队 ID 从 团队 ID
APPLE_KEY_ID__CAPGO_KEEP_0__ Apple key、Apple key ID 和 Apple 发行人 ID
APPLE_ISSUER_ID__CAPGO_KEEP_0__ Apple key、Apple key ID 和 Apple 发行人 ID
BUILD_CERTIFICATE_BASE64__CAPGO_KEEP_0__ certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP由 CLI 生成 — 复制自 .capgo-credentials 文件
APPLE_KEY_CONTENT__CAPGO_KEEP_0__ apple_key_base64.txt
P12_PASSWORD (可选)您的 .p12 如果在导出期间设置,则使用密码

3) 在您的 GitHub Actions 工作流中使用环境变量

Section titled “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 }}

现在,您已经准备好运行第一个构建。

运行以下命令以构建您的应用:

终端窗口
bunx @capgo/cli@latest build request --platform ios

恭喜 🎉 您已经成功构建了您的应用程序,它现在准备好提交到 App Store。

内部测试模式

内部测试模式

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

When to use ad-hoc mode

关于何时使用 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

创建自定义配置文件

创建自定义配置文件

步骤与上面相同 配置文件但在第五步中选择 Ad Hoc 而不是 App Store:

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

保存 ad-hoc 凭据

保存 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 构建

运行 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 构建

标题: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

具有扩展的应用(多目标签名)

标题:具有扩展的应用(多目标签名)

如果您的应用包含扩展(共享扩展、小部件、通知服务扩展等),则每个扩展目标都需要自己的签名配置文件。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"

targetLanguage --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"

故障排除:配置文件不包含 XYZ 功能。

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

复制到剪贴板

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

要解决这个问题,请重新生成配置文件。

__CAPGO_KEEP_0__

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

这应该解决问题.

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

从 iOS Builds 中继续

从 iOS Builds 中继续

如果您正在使用 iOS Builds 来规划 CI/CD 自动化, Capgo CI/CD 为 Capgo CI/CD 中的产品工作流程 Capgo Native Builds 为 Capgo Native Builds 中的产品工作流程 Capgo Integrations 为 Capgo Integrations 中的产品工作流程 CI/CD 集成 CI/CD 集成的实现细节,包括 GitHub Actions 集成 GitHub Actions 集成的实现细节,包括