iOS 构建
复制一个包含安装步骤和本插件的完整Markdown指南的设置命令。
使用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联系信息
第一个手动构建
标题:第一个手动构建在我们开始使用 Capgo 构建应用之前,我们应该先设置它,并手动完成一次TestFlight构建。 手动构建有几个优势:
- 你将在本地机器上设置分发证书
- 你将创建App Store记录,如果你还没有做的话
- 你将能够找出与应用 code 相关的构建过程中的任何问题
在我们开始之前,你必须在本地机器上安装分发证书。 这很复杂,但我将在下面解释。
设置分发证书
标题:设置分发证书-
打开Xcode
-
点击
Xcode->Settings...或者你可以使用快捷方式Cmd + ,
-
前往
Accounts
-
找到已添加到Apple Developer帐户的Apple Account

-
找到你将用于部署应用的团队

-
点击
Manage Certificates...按钮
-
确保您可以在列表中看到分发证书

-
如果您没有看到,请创建一个新的证书
- 点击
+按钮,然后点击Apple Distribution
- 证书将自动创建。您可以在列表中看到它。查看上一步以确认您看到它。
- 点击
现在您已经安装了分发证书,可以开始构建过程了。
手动构建到 TestFlight
手动构建到 TestFlight-
在 Xcode 中打开应用
运行
bunx cap open ios以在 Xcode 中打开应用。 -
找到并点击
archive按钮在 Xcode 工具栏中找到并点击
product->archive按钮。
-
等待构建完成
-
点击
Distribute App按钮
-
选择
TestFlight Internal Only作为分发方法并点击Distribute按钮
-
配置应用记录
填写以下字段:
- 名称:应用名称 - 在 App Store 中可见
- SKU - 应用 SKU - 此为在 App Store 中识别应用的标识符
- 主要语言 - 应用主要语言
然后,点击
next按钮
-
如果创建 app 记录失败,请尝试关闭窗口并再次存档 app。
-
等待上传完成
-
如果一切顺利,您应该看到以下屏幕

-
点击
Done按钮
您可能会本能地认为现在一切都好,并且您将能够在 TestFlight 中看到您的应用,但仍有几件事情需要完成:
- 将自己添加到 TestFlight 中
- 完成导出合规性,以便构建成为可测试的
- 填写必填的 App Store Connect 元数据,如支持 URL、隐私政策 URL 和年龄等级
- 准备与您实际支持的设备匹配的截图
- 添加 App Review 联系信息和任何测试凭证,生产提交之前
让我们从第一个开始:
添加自己到 TestFlight
标题:添加自己到 TestFlight-
前往 App Store Connect 页面

-
使用您的 Apple Developer 账户登录
-
选择您在创建应用记录时使用的团队。如果您只有一份开发者账户,可以跳过这个步骤。

-
点击
Appsbutton
-
在前一步骤中创建的应用程序中查找并点击它

-
点击
TestFlightbutton
-
点击
Internal Testers plusbutton
-
创建一个新组
我喜欢将组命名为“内部”。你可以给它任何名字。

-
点击
Invite testers按钮
-
添加自己到组
在列表中找到并选择下面你的名字旁边的 checkbox。 (你可能需要刷新页面才能看到自己) 然后,点击
Add按钮。
-
确认你已经添加到组
现在,你应该在组中看到自己

恭喜 🎉 你已经添加到 TestFlight。现在,还有最后一步 你需要做才能配置 Capgo Native Build。
设置应用合规信息
应用合规信息设置现在您需要向苹果公司保证您的应用程序不使用任何非标准(如自定义算法)加密。如果您的应用程序确实使用任何非标准加密,我建议阅读 苹果文档 关于如何处理此问题的说明。 有两种方法可以做到这一点:
- 您可以每次构建应用程序时手动完成此操作。
- 您可以配置您的 plist 文件,以自动将此值设置为
false.
让我们从第一种方法开始:
-
按照上一节中的所有步骤找到 App Store Connect 中的 TestFlight 部分
-
点击
Builds -> iOS
-
找到缺少合规信息的构建并点击
Manage
-
选择最能描述你的应用程序的选项
对我来说,这是
none但它可能与你不同。 然后,点击保存
-
你的应用程序现在应该说
ready to test
至于第二个,以下是步骤:
-
打开
Info.plist文件 -
添加以下键:
<key>ITSAppUsesNonExemptEncryption</key><false/> -
保存文件
安装TestFlight应用并接受邀请
安装TestFlight应用并接受邀请现在,你 快 差不多
- 准备好在TestFlight中测试你的应用了。 在此之前,你需要做以下事情: 下载TestFlight应用 从 App Store 上的 iOS/iPadOS 设备
- 接受测试你的应用的邀请
我将跳过如何在你的设备上安装 TestFlight 应用的详细步骤。如果你不确定如何安装一个应用,Google 有一些关于如何做到的很好的指南。
关于接受邀请,你将从 Apple 接收一个包含接受邀请的链接的电子邮件。
-
打开 Apple 发来的电子邮件,包含接受邀请的链接
-
点击
View in TestFlight接受测试应用的按钮
-
接受测试应用的按钮
Install点击
-
在你的设备上安装应用
如果您以前使用 Xcode 安装了该应用程序,则可能会看到以下屏幕。请单击
install按钮。
-
等待应用程序安装
-
单击
Open按钮并单击它
恭喜 🎉 您已接受 TestFlight 测试应用程序的邀请。现在,您可以配置 Capgo 原生构建来构建和提交应用程序到 TestFlight。
配置 Capgo 原生构建
标题为“配置 Capgo 原生构建”要能够构建和提交应用程序到 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
标题:团队 ID首先,我们需要找到团队 ID。找到它很容易.
-
前往 Apple 开发者账户 并滚动到底部
-
找到
Team ID
现在,让我们转到苹果密钥。
-
从下拉菜单中选择正确的团队
- 点击右上角的用户名
- 点击要使用的团队

-
点击
Integrations__CAPGO_KEEP_0__
-
找到
issuer点击
copy按钮复制发行者
-
点击加号按钮

-
设置密钥的名称并设置访问权限
App manager并点击Generate按钮
-
保存密钥ID

-
下载密钥


恭喜 🎉 您已创建 Apple 密钥、Apple 密钥 ID 和 Apple 发行者 ID。
现在,您已经准备好导出证书了。您还记得本指南的第一步是设置分布式证书吗?
然而,苹果在他们的无限智慧中决定了导出证书的方式与创建它们的方式有所不同 🙃 让我们进入设置:
-
打开 Keychain Access
- 点击
Command + Space以打开搜索栏 - 在搜索栏中查找
Keychain Access - 点击
Keychain Access应用
- 点击
-
选择
login类别并点击My Certificates按钮
-
在列表中找到您的证书
证书应该命名为
Apple Distribution: [Your Name/Company] (your team ID)
-
右键单击证书并选择
Export
-
将证书保存为一个
.p12文件- 确保为证书文件选择一个合适的名称
- 确保文件格式设置为
Personal Information Exchange (.p12) - 点击
Save按钮

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

- 跳过密码(推荐的简便方式):点击
-
当被要求输入“登录密钥链密码”时,请输入您用于登录 Mac 的密码
输入您用于登录 Mac 的密码。然后,点击
Allow按钮。
恭喜 🎉 您已成功导出证书。
配置文件
标题为“配置文件”的部分现在,您已经准备好从 Apple 导出配置文件了。相信我,这是您从 Apple 需要的最后一件事。
-
选择正确的团队
- 点击右上角的你的名字
- 点击你要使用的团队

-
确保你在正确的页面 它应该看起来像这样,如果不然点击
profiles在侧边栏
-
点击
+按钮
-
选择配置文件类型 选择
App Store Connect并点击Continuebutton
-
选择您要构建的应用
在下拉菜单中找到您的应用并点击
Continuebutton
-
选择正确的分发证书
选择您在上一步中导出的证书并点击
Continuebutton
如果您不确定要选择哪个证书,请返回 Keychain Access,找到您导出的证书,然后查看有效期

-
命名配置文件
为配置文件命名并点击
Generate按钮
-
下载配置文件
点击
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如果一切顺利,下面将显示输出结果:

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.txt2)创建仓库密钥
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 工作流中使用环境变量”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-uploadwithout 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:
- 前往 Apple Developer配置文件
- 点击
+按钮 - 选择 Ad Hoc 并点击继续
- 选择您的应用程序和分发证书
- 选择您要注册的设备
- 命名并下载配置文件
保存 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 需要。
运行一个临时构建
标题:运行一个临时构建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 构建少的密钥:
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:
- 自动从嵌入的plist中提取配置文件名称
- 以Base64编码文件
- 将所有内容存储为一个
- 凭证
CAPGO_IOS_PROVISIONING_MAPSection 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"__CAPGO_KEEP_0__不包含 XYZ 能力。
__CAPGO_KEEP_1__标题:__CAPGO_KEEP_0__不包含 XYZ 能力。有时您可能会看到以下错误:
Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"这是因为您在创建配置文件后启用了新能力。 旧的配置文件还没有包含新能力。
要解决这个问题,您需要重新生成配置文件。
- 打开 Apple 开发者门户
- 在下拉菜单中选择正确的团队

- 点击
Profiles__CAPGO_KEEP_2__
- 找到您要重新生成的分发配置文件

- 点击
Edit按钮
- 点击
Save按钮
- 点击
Download按钮
- 重新运行 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.