iOS 构建

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

构建前准备

⚠️ 首先设置 iOS 凭证

必需: 在构建之前,您必须保存 iOS 凭证。

设置 iOS 凭证 →

iOS 构建的工作原理

iOS 构建在按需配置的专用 Mac 机器(Scaleway Mac minis M4)上运行:

硬件: 带有 macOS 15 的 Apple Silicon Mac minis
构建工具: Xcode 与 Fastlane(自定义 Capgo 配置)
隔离: 每个构建作为单独的 macOS 用户账户运行
生命周期: 机器有 24 小时租期,并自动清理
安全性: 机器被释放后,所有文件和用户账户都被删除

前置条件

在为 iOS 构建之前,您需要:

1. 开发环境

本地安装了 Xcode 的 Mac 计算机(用于初始证书设置)
有效的 Apple Developer 账户($99/年)
您的应用能够成功使用 npx cap open ios 构建

2. 代码签名证书

根据您的构建,您需要以下证书类型之一:

构建类型	需要证书	配置文件
Development	Apple Development	Development Profile
Ad Hoc	Apple Distribution	Ad Hoc Profile
App Store	Apple Distribution	App Store Profile

如何获取 iOS 证书和配置文件

快速概述:

创建证书签名请求(CSR)
- 在 Mac 上打开钥匙串访问
- 前往钥匙串访问 → 证书助理 → 从证书颁发机构请求证书
- 输入您的电子邮件和姓名,选择”存储到磁盘”
- 保存 .certSigningRequest 文件
在 Apple Developer Portal 中生成证书
- 前往 Apple Developer 证书
- 点击”+“创建新证书
- 选择证书类型(App Store 构建需要 iOS Distribution)
- 上传您的 CSR 文件
- 下载证书(.cer 文件)
将证书导出为 .p12
- 双击下载的 .cer 文件将其添加到钥匙串
- 在钥匙串访问中,在”我的证书”下找到您的证书
- 右键点击 → 导出”Apple Distribution…”
- 保存为 .p12 格式并设置密码(保存此密码!)
创建配置文件
- 前往 Apple Developer 配置文件
- 点击”+“创建新配置文件
- 选择配置文件类型(生产构建需要 App Store)
- 选择您的 App ID
- 选择您刚刚创建的证书
- 下载 .mobileprovision 文件

3. App Store Connect API 密钥(推荐)

要自动提交到 TestFlight,创建 API 密钥:

前往 App Store Connect → 用户和访问 → 密钥
点击”+“按钮创建新密钥
给它一个名称(例如,“Capgo CI”)并选择”开发者”角色
下载 .p8 文件(您只能下载一次!)
记下密钥 ID 和发行者 ID

构建配置

必需的环境变量

在构建前设置这些凭证:

# iOS 签名(必需)
BUILD_CERTIFICATE_BASE64="<base64编码的p12证书>"
BUILD_PROVISION_PROFILE_BASE64="<base64编码的mobileprovision>"
P12_PASSWORD="<证书密码>"

# App Store Connect API(用于提交)
APPLE_KEY_ID="ABC1234567"
APPLE_ISSUER_ID="00000000-0000-0000-0000-000000000000"
APPLE_KEY_CONTENT="<base64编码的p8密钥>"

# 附加配置
APP_STORE_CONNECT_TEAM_ID="1234567890"
APPLE_PROFILE_NAME="App Store com.example.app"

生成 Base64 凭证

证书(.p12):

base64 -i YourCertificate.p12 | pbcopy

配置文件(.mobileprovision):

base64 -i YourProfile.mobileprovision | pbcopy

App Store Connect 密钥(.p8):

base64 -i AuthKey_ABC1234567.p8 | pbcopy

base64 字符串现在在您的剪贴板中 - 将其粘贴到您的环境变量或 CI/CD 密钥中。

为 iOS 构建

Debug 构建(开发)

npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode debug

这会创建一个可以安装在已注册设备上的开发构建。

Release 构建(App Store)

npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

如果您配置了 App Store Connect API 凭证,这会创建 App Store 构建并自动提交到 TestFlight。

CI/CD 集成

GitHub Actions 示例

name: Build iOS App

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Install dependencies
        run: npm ci

      - name: Build web assets
        run: npm run build

      - name: Sync Capacitor
        run: npx cap sync ios

      - name: Build iOS app
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.IOS_PROVISION_PROFILE }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.TEAM_ID }}
        run: |
          npx @capgo/cli@latest build ${{ secrets.APP_ID }} \
            --platform ios \
            --build-mode release

构建过程详情

iOS 构建期间发生的事情

机器配置 (1-2分钟)
- 配置或分配 Scaleway Mac mini
- 预装 Xcode 的 macOS 15
- 运行引导脚本(如果首次使用)
用户隔离 (~10秒)
- 创建唯一的 macOS 用户: job-<jobId>
- 专用主目录: /Users/job-<jobId>
- 创建隔离的工作空间
项目设置 (~30秒)
- 从 R2 下载项目压缩包
- 解压到工作空间
- 作为环境变量注入凭证
Fastlane 构建 (3-8分钟)
- 使用签名证书创建钥匙串
- 安装配置文件
- 执行 Xcode 构建命令
- 生成 IPA 文件
App Store 提交 (1-2分钟,如果配置)
- IPA 上传到 App Store Connect
- 提交到 TestFlight
- 在 Apple 端开始处理
清理 (立即)
- 终止并删除用户账户
- 删除工作空间文件
- 清除临时文件
机器释放 (24小时后)
- 销毁 Mac 机器
- 所有数据永久删除

构建堆栈

我们的 iOS 构建环境包括:

macOS: 15(最新稳定版)
Xcode: 最新稳定版本
Fastlane: 最新稳定版本
CocoaPods: 最新稳定版本
Node.js: 18.x (LTS)
Ruby: 系统 ruby 与 bundler

构建时间

典型的 iOS 构建时间:

构建类型	首次构建	后续构建*
Debug	5-7 分钟	4-6 分钟
Release	7-10 分钟	5-8 分钟

*如果在 24 小时窗口内重用同一台机器,后续构建可能更快。

故障排除

常见问题

“Code signing failed”

验证您的证书是否适用于正确的分发类型
确保配置文件与您的 App ID 匹配
检查 P12_PASSWORD 是否正确

“Provisioning profile doesn’t include signing certificate”

重新生成包含证书的配置文件
重新下载并重新编码配置文件

“App Store Connect authentication failed”

验证 APPLE_KEY_ID、APPLE_ISSUER_ID 和 APPLE_KEY_CONTENT
确保 API 密钥未被撤销
检查密钥是否具有”开发者”角色或更高权限

“Build timeout after 10 minutes”

检查您的应用是否有大型原生依赖项
考虑优化您的 Podfile
如果构建持续超时,请联系支持

调试日志

所有构建日志都实时流式传输。注意这些关键阶段:

✔ Machine assigned: m-abc123
→ Creating user: job-abc123
→ Installing CocoaPods dependencies...
→ Building iOS app...
→ Code signing with certificate...
→ Uploading to App Store Connect...
✔ Build succeeded

如果构建失败,日志中将清楚地显示错误,并提供具体的 Fastlane/Xcode 错误消息。

最佳实践

1. 首先在本地测试

在使用云构建之前,始终确保您的 iOS 构建在本地可以工作:

npx cap open ios
# 在 Xcode 中构建

2. 使用环境变量

切勿将证书或密钥提交到存储库。始终使用:

CI/CD 密钥(GitHub、GitLab)
环境变量
安全的密钥管理

3. 缓存依赖项

为了更快的构建,确保您的 package.json 和 Podfile.lock 已提交到版本控制。

4. 监控构建时间

密切关注构建持续时间以优化成本:

# CLI 在最后显示构建时间
Build succeeded in 6m 42s (13.4 billing minutes at 2× rate)

下一步

Android 构建 - 配置 Android 构建
故障排除 - 常见构建问题
CLI 参考 - 完整命令文档