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

-
找到您将用于部署应用程序的团队

-
点击
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按钮
-
添加自己到组
在列表中找到并选择下面你的名字旁边的复选框。 (你可能需要刷新页面才能看到自己) 然后,点击
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中测试您的应用了。 在此之前,您需要完成以下步骤: 下载 从 App Store 上的 iOS/iPadOS 设备
- 接受测试你的应用的邀请
我将跳过如何在你的设备上安装 TestFlight 应用的详细步骤。如果你不确定如何安装一个应用,Google 有一些关于如何做到的很好的指南。
关于接受邀请,你将从 Apple 接收一个包含邀请链接的电子邮件。
-
打开 Apple 发来的电子邮件,包含邀请链接
-
点击
View in TestFlightTestFlight 邀请按钮
-
TestFlight 安装按钮
Install在你的设备上安装应用
-
Open the email from Apple with the link to accept the invitation.
如果您以前使用 Xcode 安装了该应用程序,则可能会看到以下屏幕。请单击
install按钮。
-
等待应用程序安装
-
单击
Open按钮并单击它
恭喜 🎉 您已接受 TestFlight 测试应用程序的邀请。现在,您可以配置 Capgo 原生构建来构建和提交应用程序到 TestFlight。
配置 Capgo 原生构建
标题为“配置 Capgo 原生构建”要能够构建和提交应用程序到 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
标题:团队 ID首先我们需要找到团队 ID。找到它很容易.
-
前往 Apple 开发者账户 并向下滚动
-
找到
Team ID
现在,让我们继续到苹果密钥。
-
并且一个引导式窗口打开App Store Connect,带您走过每一步,并自动捕获密钥、Key ID和Issuer ID——无需复制粘贴。以下的手动步骤是替代方案(以及Windows或Linux上的路径)。 前往
-
选择正确的团队在下拉菜单中
- 点击右上角的你的名字
- 点击你要使用的团队

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

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

-
下载密钥


恭喜你 🎉 你已经创建了Apple密钥、Apple密钥ID和Apple发行者ID。
证书
证书现在,你准备好导出证书了。回想一下,这个指南的第一步是设置分布式证书。
然而,苹果公司在他们的无限智慧中,决定导出证书的方式与创建证书的方式有所不同 🙃 让我们进入设置:
-
打开钥匙串访问
- 点击
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不输入密码 - 设置密码:如果您希望保护证书使用密码,
.p12files are fully supported by the Capgo CLI - just provide the password using the--p12-password文件完全支持__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - 只需使用

- 跳过密码(推荐简化):点击
-
Keychain Access 保存证书密码对话框
当被要求输入“登录密钥链密码”时,请输入您用来登录Mac的密码
Allow输入您用来登录Mac的密码。然后,点击
恭喜你 🎉 你已经导出了证书。
配置文件
配置文件现在,你已经准备好导出配置文件了。相信我,这是你从苹果那里需要做的最后一件事。
-
前往 苹果开发者配置文件
-
在下拉菜单中选择正确的团队
- 点击右上角的你的名字
- 点击你要使用的团队

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

-
命名配置文件
为配置文件命名并点击
Generatebutton
-
下载资料
点击
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)

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.txt2) 创建仓库秘密
标题: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 工作流中使用环境变量”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:
- 前往 Apple Developer Profiles
- 点击
+按钮 - 选择 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 需要
运行 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-uploadCI/CD 与 ad-hoc 构建
标题:CI/CD 与 ad-hoc 构建对于 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 标志
示例:应用+共享扩展
终端窗口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:
- 读取每个 mobileprovision 文件
- 自动从嵌入的 plist 中提取配置文件名称
- 将文件进行 Base64 编码
- 将所有内容存储为单个
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 功能。故障排除:配置文件不包含 XYZ 功能。
有时您可能会看到以下错误:复制到剪贴板
Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"要解决这个问题,请重新生成配置文件。
__CAPGO_KEEP_0__
- 打开 苹果开发者门户
- 从下拉菜单中选择正确的团队

- 点击
Profiles苹果开发者配置文件按钮
- 苹果开发者找到配置文件

- 苹果开发者编辑配置文件按钮
Edit__CAPGO_KEEP_0__
- 点击
Save按钮
- 点击
Download按钮
- 重新运行 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 集成的实现细节,包括