跳过内容

iOS 构建

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

你将学到什么

标题:你将学到什么
  • 您将学习如何通过 Capgo 原生构建上传您的应用
  • 您将学习如何配置 Capgo 原生构建的证书
  • 一个 Capgo 账户(免费试用即可开始)
  • 您的应用已在 Capgo 中注册(运行 bunx @capgo/cli@latest app add 如果没有)
  • 一台安装了 Xcode 的 Mac 电脑(可以在 Linux/Windows 机器上设置构建,但尚未文档化)
  • 有效的 Apple Developer 账户($99/年)(您必须在 Apple Developer 账户上具有管理员或所有者权限)
  • 您的应用必须能够通过 Xcode 构建成功
  • 一个 Capacitor 应用
  • 一个已配置的应用图标。无法上传到 App Store 的应用没有图标。

在开始使用 Apple 的门户之前

标题:在 Apple 的门户之前

在设置证书或触发首次 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注册的Web过程 选择正确的 Apple Developer 实体类型 App Store Connect 注册后

第一个手动构建

标题:第一个手动构建

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

  • 你将在本地机器上设置分发证书
  • 你将创建App Store记录,如果你还没有做的话
  • 你将能够找出与应用 code 相关的构建过程中的任何问题

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

设置分发证书

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

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

    Xcode设置

  3. 前往 Accounts Xcode账户标签

  4. 找到已添加到Apple Developer帐户的Apple Account 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 应用程序按钮

  5. 在前一步骤中创建的应用程序中查找并点击它 App Store Connect 应用程序选择

  6. 点击 TestFlight button App Store Connect 测试飞行按钮

  7. 点击 Internal Testers plus button App Store Connect 内部测试者加号按钮

  8. 创建一个新组

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

    App Store Connect 创建新组

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

  10. 添加自己到组

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

    App Store Connect 邀请测试者 checkbox

  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中测试你的应用了。 在此之前,你需要做以下事情: 下载TestFlight应用 从 App Store 上的 iOS/iPadOS 设备
  2. 接受测试你的应用的邀请

我将跳过如何在你的设备上安装 TestFlight 应用的详细步骤。如果你不确定如何安装一个应用,Google 有一些关于如何做到的很好的指南。

关于接受邀请,你将从 Apple 接收一个包含接受邀请的链接的电子邮件。

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

  2. 点击 View in TestFlight 接受测试应用的按钮 点击

  3. 接受测试应用的按钮 Install 点击 安装应用的按钮

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

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

  5. 等待应用程序安装

  6. 单击 Open 按钮并单击它

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

要能够构建和提交应用程序到 TestFlight,您需要在 Capgo 原生构建中配置一些东西。 以下是您将传递给 Capgo CLI:

参数描述
--platform用于构建的平台(ios)
--apple-team-id您的Apple Developer Team ID(在 Apple Developer Portal)
--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 用户和访问页面

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

    1. 点击右上角的用户名
    2. 点击要使用的团队 苹果开发者密钥团队选择
  3. 点击 Integrations __CAPGO_KEEP_0__ 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. 打开 Keychain Access

    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 在 Keychain Access 中导出证书

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

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

    Keychain Access 保存证书对话框

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

    • 跳过密码(推荐的简便方式):点击 OK 不输入密码
    • 设置密码:如果您愿意保护证书文件使用密码, .p12 您可以在此处设置一个。使用密码保护的文件完全支持 Capgo CLI - 只需使用密码即可 --p12-password 运行配置命令时的选项。

    Keychain Access 保存证书密码对话框

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

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

    Keychain Access 保存证书登录密钥链密码

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

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

  1. 前往 Apple Developer Profiles

  2. 选择正确的团队

    1. 点击右上角的你的名字
    2. 点击你要使用的团队 Apple Developer keys团队选择
  3. 确保你在正确的页面 它应该看起来像这样,如果不然点击 profiles 在侧边栏

    Apple Developer profiles页面

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

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

    Apple Developer 选择用户类型

  6. 选择您要构建的应用

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

    Apple Developer 选择应用

  7. 选择正确的分发证书

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

    Apple Developer 选择分发证书

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

    Apple Developer 选择分发证书有效期

  8. 命名配置文件

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

    Apple Developer 名称配置文件

  9. 下载配置文件

    点击 Download 按钮下载配置文件

    Apple Developer 下载配置文件

恭喜 🎉 您现在已经准备好配置 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

如果一切顺利,下面将显示输出结果:

Capgo CLI 凭据保存输出

CI/CD 设置 (GitHub Actions)

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

如果您已经完成了 团队 ID, Apple 密钥、Apple 密钥 ID 和 Apple 发行者 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您的CapgoAPI令牌
APP_STORE_CONNECT_TEAM_ID团队ID从 团队ID
APPLE_KEY_ID密钥ID从 苹果密钥、苹果密钥ID和苹果发行者ID
APPLE_ISSUER_ID发行者ID从 苹果密钥、苹果密钥ID和苹果发行者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 工作流中使用环境变量

标题为“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 艺术品收集),则可以使用 --ios-distribution 标志

您想直接将IPA分发给注册的设备(不使用TestFlight)

您没有或不想使用App Store Connect__CAPGO_KEEP_0__密钥
  • 您想通过
  • 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

自定义构建有 比App Store构建少 一些要求:

凭证是否必需
分布式证书(.p12)
自定义构建配置文件(.mobileprovision)
团队ID(--apple-team-id)
App Store Connect API key(.p8)
Apple Key ID / Issuer ID

创建 ad-hoc 配置文件

创建 ad-hoc 配置文件

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

  1. 前往 Apple Developer配置文件
  2. 点击 + 按钮
  3. 选择 Ad Hoc 并点击继续
  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

CI/CD with ad-hoc builds

对于 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 flag.

示例: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"

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

  1. 自动从嵌入的plist中提取配置文件名称
  2. 以Base64编码文件
  3. 将所有内容存储为一个
  4. 凭证 CAPGO_IOS_PROVISIONING_MAP Section titled “Example: App + Share Extension”

从单一配置文件迁移

标题:从单一配置文件迁移

如果您以前使用过 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"

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

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

这是因为您在创建配置文件后启用了新能力。 旧的配置文件还没有包含新能力。

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

  1. 打开 Apple 开发者门户
  2. 在下拉菜单中选择正确的团队 Apple 开发者密钥团队选择
  3. 点击 Profiles __CAPGO_KEEP_2__ Apple Developer profiles 按钮
  4. 找到您要重新生成的分发配置文件 Apple Developer 查找配置文件
  5. 点击 Edit 按钮 Apple Developer 编辑配置文件
  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 原生构建 为产品工作流程在 Capgo 原生构建 中 Capgo 集成 为产品工作流程在 Capgo 集成 中 CI/CD 集成 CI/CD 集成的实现细节 GitHub 动作集成 for the implementation detail in GitHub Actions Integration.