开始

使用 Capgo Cloud Build，仅需几分钟即可创建您的第一个 iOS 或 Android 原生构建。

您需要的内容

开始之前，请确保您有：

• 一个 Capacitor 应用程序，能够在本地成功构建
• 安装了 Node.js 20 或更高版本
• 一个 Capgo 帐户（免费试用即可开始）
• 您的应用程序已经在 Capgo 中注册（运行 npx @capgo/cli@latest app add 如果没有)
• (不需要提前准备签名凭证 — 我们将在下一步中设置它们。)

配置您的签名凭证

Capgo需要签名凭证才能构建和提交您的应用程序 — 但您不必手动处理它们。回答几个问题，我们将指向您需要运行的exact命令：

运行您的第一个构建

您需要使用Capgo进行身份验证才能构建。如果您尚未：

npx @capgo/cli@latest login
# or, in CI, set the token directly:
export CAPGO_TOKEN=your_api_key

如果您刚刚运行 build init,您已经准备好了 — 该引导程序在结束时提供了开始构建的选项，因此您的第一个构建可能已经在路上。 🎉

否则，自己启动一个构建过程 build request — 设置 --platform 到你正在构建的任何地方：

npx @capgo/cli@latest build request com.example.app --platform <android|ios> --build-mode debug

CLI 将准备好的本机项目上传并在您的终端中实时流式传输构建日志。 Capgo 构建可以返回签名的艺术品或将其提交到 App Store Connect 或 Google Play，具体取决于您配置的适当发布流程。

了解构建过程

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

flowchart LR
    A[Your CI] -->|1. Prepare Native Project| B[Prepared iOS / Android Project]
    B -->|2. Upload| C[Capgo Build]
    C -->|3. Compile and Sign| D[Dedicated Build Infrastructure]
    D -->|4. Stream Logs| E[Your Terminal]
    D -->|Return Signed Artifact or Store Delivery| F[Output]
    D -->|5. Clean Temporary Project Data| G[Cleanup]

1. 在 CI 中准备 - 构建 web 层，解决私有依赖项，并将完成的资产同步到本机项目。
2. 上传 - 已准备的原生项目上传到安全的云存储中用于构建。
3. 构建执行 - Capgo 在专用基础设施上编译和签署原生项目。
4. 日志流 - 实时日志通过 Server-Sent Events 流向您的终端。
5. 清理 - 构建环境和临时项目数据在构建后清理；输出保留依赖于所选的工件和存储交付选项。

使用 Capgo Build 与 Bitrise 或另一个 CI

Capgo Build 不会替换您的现有 CI。保留需要私有访问的步骤：从私有注册表中安装、通过 SSH 解析私有 CocoaPods、运行自定义原生设置、构建 web 层和运行 npx cap sync.

然后调用 Capgo Build 使用已准备的原生项目。Capgo 将接收准备好的项目。 ios/ 或 android/ 项目以编译和签名，因此不需要您的私有 Nexus、CocoaPods SSH 或 web-build 凭据。已编译的 Web 资产已经包含在该准备好的本机项目中；它们用于构建而不是保留为源代码仓库。

What Gets Built

Capgo Build 接收所需的准备好的本机项目以编译您的应用。您的 Web 源 code、私有依赖安装和 Capacitor 同步仍然保留在您的 CI 中。

What Gets Uploaded

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

什么没有上传

被排除	为什么
node_modules/ （大部分）	仅有本机插件 code 被包含，JS依赖不被包含
src/	您的 Web 源 code 仍然是本地的
dist/, www/, build/ (根级别)	已同步到本地文件夹中的 cap sync
.git/	版本控制历史
.gradle/, .idea/, .swiftpm/	构建缓存和 IDE 设置
.env, 秘密	从未上传

注意

您的构建 Web 资产 (JS、CSS 和 HTML) 只是因为 npx cap sync 已复制到本地项目中。 Web 源和依赖安装步骤仍然在您的 CI 中; 准备好的本地项目用于构建二进制文件，然后清理。

您的责任

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

1. 在 CI 中准备 - 在 Bitrise 或您的现有 CI 中解决私有包注册表、基于 SSH 的 CocoaPods、设备 SDK、扩展和任何自定义本机准备。
2. 构建您的 Web 资产 - 运行 npm run build (或您的框架的构建命令).
3. 同步到本机 - 运行 npx cap sync 将编译的 Web 资产复制到准备好的本机项目中。
4. 请求本机构建 - 发送准备好的 ios/ 或 android/ 项目到 Capgo Build.

What Capgo Build Handles

• 原生 iOS 编译 (Xcode, Fastlane)
• 原生 Android 编译 (Gradle)
• Code 使用您的凭据签名
• 可选 App Store Connect 或 Google Play 提交
• 支持的原生构建配置和凭据值通过环境变量传递

Capgo Build 不需要访问您的私有 Nexus 仓库或 SSH 凭据，一旦您的 CI 准备好原生项目，见 构建配置 支持的环境变量和存储选项。

For a kiosk flavour distributed through MDM, configure the Android project/build to produce an APK. When requesting the build, use both flags to skip Google Play and retrieve the signed output:

npx @capgo/cli@latest build request YOUR_APP_ID --platform android --no-playstore-upload --output-upload

--no-playstore-upload 即使保存了Play商店凭证，仍然会阻止Play Store上传; --output-upload 提供一个时间限制的链接到签名输出。通过MDM分发该APK。

下一步

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

• 配置iOS构建 - 设置证书和配置文件
• 配置Android构建 - 设置密钥库和Play Store
• 故障排除 - 常见问题和解决方案
• CLI 参考 - 完整命令文档

需要帮助?

• 查看 故障排除指南
• 加入我们的 Discord 社区
• 通过电子邮件 support@capgo.app