快速入门

开始使用 Capgo Cloud Build，几分钟内即可创建你的第一个 iOS 或 Android Native Build。

准备工作

开始前，请确保你已具备：

• 一个可在本地成功构建的 Capacitor app
• 已安装 Node.js 20 或更高版本
• 一个 Capgo 账号（免费试用即可开始）
• 你的应用已在 Capgo 中注册（请运行 npx @capgo/cli@latest app add 如未注册）
• （无需提前准备签名凭据——下一步我们会帮你配置好。）

配置签名凭据

Capgo 需要签名凭据才能构建并提交你的应用——但你不用手动折腾这些。回答几个问题，我们会告诉你具体该运行哪条命令：

运行你的第一个 Build

你需要先通过 Capgo 身份验证才能构建。如果还没登录：

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

如果你刚运行了 build init，那你就已经就绪了 —— onboarding 最后会提供为你启动 build 的选项，所以你的首次 build 可能已经在路上了。🎉

否则，你可以自己用以下命令启动 build： build request — 将 --platform 设置为你正在构建的目标平台：

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

CLI 会上传准备好的原生项目，并在你的终端中实时流式输出 build logs。配置好相应的发布流程后，Capgo Build 可以返回已签名的构建产物，或将其提交到 App Store Connect 或 Google Play。

了解 Build 流程

运行 build 命令时，会发生以下情况：

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 层，解析私有依赖，并将构建完成的 assets 同步到原生项目中。
2. 上传 - 准备好的原生项目会上传到安全的云存储以进行构建。
3. 构建执行 - Capgo 在专用基础设施上编译并签名原生项目。
4. 日志流式传输 - 实时日志通过 Server-Sent Events 流式传输到您的终端。
5. 清理 - 构建完成后，构建环境和临时项目数据会被清理；输出保留策略取决于所选的产物和商店交付选项。

配合 Bitrise 或其他 CI 使用 Capgo Build

Capgo Build 不会替代您现有的 CI。请在 Bitrise 或其他 CI 系统中保留需要私有访问权限的步骤：从私有注册表安装依赖、通过 SSH 解析私有 CocoaPods、运行自定义原生配置、构建 Web 层，并执行 npx cap sync.

然后调用 Capgo Build 处理准备好的原生项目。Capgo 将接收就绪的 ios/ 或 android/ 用于编译和签名的项目，因此不需要你的私有 Nexus、CocoaPods SSH 或 web-build 凭据。编译后的 Web 资源已包含在这个准备好的原生项目中，仅用于构建，不会作为源码仓库保留。

构建内容

Capgo Build 会接收编译应用所需的、已准备好的原生项目。你的 Web 源码 code、私有依赖安装以及 Capacitor 同步仍留在你的 CI 中。

上传内容

包含	描述
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 （或您框架的 build 命令）。
3. 同步到原生 - 运行 npx cap sync 将编译后的 web 资源复制到已准备好的原生项目中。
4. 请求 Native Build - 发送已准备好的 ios/ 或 android/ 将项目交给 Capgo Build。

Capgo Build 处理的内容

• 原生 iOS 编译（Xcode、Fastlane）
• 原生 Android 编译（Gradle）
• 使用你的凭据完成 Code 签名
• 可选提交至 App Store Connect 或 Google Play
• 支持通过环境变量传入的原生 build 配置和凭据值

CI 准备好原生项目后，Capgo Build 无需访问你的私有 Nexus 仓库，也不需要你的 SSH 凭据。参见 Build 配置 了解支持的环境变量和商店选项。

对于通过 MDM 分发的 kiosk 版本，请将 Android 项目/构建配置为生成 APK。请求构建时，同时使用这两个 flag 跳过 Google Play，并获取已签名的产物：

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 构建 - 设置 keystore 和 Play Store
• 故障排除 - 常见问题与解决方案
• CLI 参考文档 - 完整的命令文档

需要帮助？

• 查看 故障排除指南
• 加入我们的 Discord 社区
• 发送邮件至支持团队 support@capgo.app