开始

使用 Capgo Cloud Build 在几分钟内创建您的第一个 iOS 或 Android 原生构建。

您需要的内容

开始之前，请确保您有：

• 一个可以在本地成功构建的 Capacitor 应用
• 安装了 Node.js 20 或更高版本
• 一个具有有效订阅的 Capgo 帐户
• 您的应用已在 Capgo 中注册（如果没有，请运行 bunx @capgo/cli@latest app add 配置了构建凭据
• (证书、密钥库) - 请参见下文 首次构建之前

标题：首次构建之前

⚠️ 首先设置凭证

在构建之前需要: 您必须配置您的构建凭证（iOS的证书，Android的keystore）。

设置凭证 →

快速入门

1. 设置构建凭证

   在您可以构建之前，您需要将凭证保存到本地:

   对于iOS：

   bunx @capgo/cli@latest build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --p12-password "password" \
     --provisioning-profile ./profile.mobileprovision \
     --apple-key ./AuthKey.p8 \
     --apple-key-id "KEY123" \
     --apple-issuer-id "issuer-uuid" \
     --apple-team-id "team-id"

   对于Android：

   bunx @capgo/cli@latest build credentials save \
     --platform android \
     --keystore ./release.keystore \
     --keystore-alias "my-key" \
     --keystore-key-password "key-pass" \
     --keystore-store-password "store-pass"

   查看 完整凭证指南 详细信息。

2. 验证本地构建

   首先，确保您的应用程序在本地没有错误：

   # Build your web assets
   bun run build
   
   # Sync with Capacitor
   bunx cap sync
   
   # Test local build (optional but recommended)
   bunx cap open ios    # For iOS
   bunx cap open android # For Android

3. 使用Capgo进行身份验证

   设置您的Capgo API密钥（如果尚未配置）：

   bunx @capgo/cli@latest login

   或设置环境变量:

   export CAPGO_TOKEN=your_api_key_here

4. 运行您的第一个构建

   从一个 Android debug 构建开始（最快的测试方式）：

   bunx @capgo/cli@latest build com.example.app \
     --platform android \
     --build-mode debug

   您将看到实时日志，随着构建的进行：

   ✔ Creating build job...
   ✔ Uploading project (15.2 MB)...
   ✔ Build started
   
   📝 Build logs:
   → Installing dependencies...
   → Running Gradle build...
   → Signing APK...
   ✔ Build succeeded in 3m 42s

5. 查看构建状态

   CLI 将自动轮询并显示构建状态。完成后，您将看到：

   • 构建时间
   • 成功/失败状态
   • 如果配置了凭据，应用程序已提交到App Store/Play Store

了解构建过程

当您运行构建命令时，以下是发生的事情：

flowchart LR
    A[Your Machine] -->|1. Zip Project| B[Local Temp]
    B -->|2. Upload| C[Capgo Cloud]
    C -->|3. Build| D[Mac Mini Silicon M4 Build Server]
    D -->|4. Logs Stream| A
    D -->|5. Cleanup| E[Auto Delete]

1. 本地准备 - 项目被压缩（排除 node_modules 和点文件）
2. 上传 - 压缩包上传到安全云存储（Cloudflare R2）
3. 构建执行 - 你的应用程序在专用基础设施上构建
4. 日志流 - 实时日志通过 Server-Sent Events 流式传输到你的终端
5. 自动清理 - 构建产物被删除 (Android: 立即, iOS: 24 小时)

构建基础设施

构建执行在专用 Mac Mini Silicon M4 机器上运行：

• 10 核 M4 CPU (4 个性能核, 6 个高效核)
• 10 核 GPU
• 16 核神经引擎
• 16GB的RAM
• macOS Tahoe 26.2

本构建镜像支持Xcode 26.2、Android Studio 2025 和 .NET 9/.NET 10 SDK 本地构建管道的工作负载。

您的第一个生产构建

一旦您验证了该过程有效，请创建一个生产构建：

Android

bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

您需要配置签名凭证才能继续。请参见 Android Build Configuration.

iOS

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

iOS构建需要签名证书和配置文件。请参阅 iOS构建配置.

构建什么

Capgo仅上传 编译您的本机应用所需的 code将永远不会离开您的机器。

上传什么

包含	描述
ios/ 或 android/	您正在构建的原生平台文件夹
package.json, package-lock.json	依赖项清单
capacitor.config.*	Capacitor 配置
resources/	应用图标、启动屏幕
原生插件 code	仅有 ios/ 或 android/ 每个 Capacitor 插件的子文件夹

什么没有上传

排除	为什么
node_modules/ (大部分)	只有本地原生插件 code 包括，JS依赖不包括
src/	您的网页源 code 保持在本地
dist/, www/, build/ (根级)	已经同步到本地文件夹中的 cap sync
.git/	版本控制历史
.gradle/, .idea/, .swiftpm/	构建缓存和IDE设置
.env机密信息	__CAPGO_KEEP_0__

注意

您的构建的 Web 资产 (JS, CSS, HTML) 已 上传 - 但作为原生文件夹的一部分。 当您运行 bunx cap sync,您的 Web 构建将被复制到 ios/App/App/public/ 或 android/app/src/main/assets/public/。 因此，运行 cap sync 之前构建是必需的。

您的责任

在运行之前 bunx @capgo/cli@latest build:

1. 构建您的 Web 资产 - 运行 bun run build (或您的框架的构建命令)
2. 同步到本机 - 运行 bunx cap sync 以将 Web 资产复制到本机项目
3. 提交依赖项 - 确保所有本机插件都在 package.json

什么 Capgo Build 处理

• 本机 iOS 编译 (Xcode, Fastlane)
• 原生 Android 编译 (Gradle)
• Code 使用您的凭据进行签名
• 如果配置了，应用商店提交

构建时间与成本

构建时间从开始到完成测量：

• Android: 通常 3-5 分钟
• iOS: 通常 5-10 分钟
• 基础设施: 运行 macOS Tahoe 26.2 的 Mac Mini Silicon M4 机器

您只为实际使用的构建时间付费。无任何隐藏费用。

常见用例

CI/CD 集成

触发 Capgo 构建，自动从您的 GitHub Actions 工作流中触发 — 在推送、标签或手动按钮点击时。请参阅专门的 GitHub Actions 指南 ，了解完整的工作流程示例，涵盖手动触发器、基于标签的发布和持续调试构建。

本地开发

在提交之前测试本地构建：

# Quick debug build for testing
bun run build && bunx cap sync
bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode debug

多平台构建

通过运行两个命令来为两个平台构建：

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

# Android build
bunx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

在CI/CD中，您可以并行运行这些任务以实现更快的构建。

下一步

您已经创建了第一个构建：

• 配置iOS构建 - 设置证书和配置文件
• 配置 Android 构建 - 配置.keystore 和 Google Play 商店
• 故障排除 - 常见问题和解决方案
• CLI 参考 - 完整命令文档

需要帮助?

• 检查 故障排除指南
• 加入我们的 Discord 社区
• 联系我们的支持团队 支持@capgo.app