开始使用

使用 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 构建可以返回一个签名的 artifact 或将其提交到 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. 日志流 - 实时日志通过服务器发送事件流式传输到您的终端。
5. 清理 在构建后，构建环境和临时项目数据将被清理；输出保留取决于所选的工件和存储交付选项。

使用 Capgo 与 Bitrise 或另一个 CI 构建

然后调用 Capgo 构建，使用准备好的原生项目。 __CAPGO_KEEP_1__ 接收准备好的 npx cap sync.

Then call Capgo Build with the prepared native project. Capgo receives the ready ios/ 使用 __CAPGO_KEEP_0__ 构建与 Bitrise 或另一个 CI android/ 然后调用 __CAPGO_KEEP_0__ 构建，使用准备好的原生项目。 __CAPGO_KEEP_1__ 接收准备好的

项目以便编译和签名，因此它不需要您的私有 Nexus、CocoaPods SSH 或 web-build 凭证。已编译的 web 资产已经包含在该准备好的原生项目中；它们用于构建，而不是保留为源代码仓库。

Capgo Build receives the prepared native project required to compile your app. Your web source code, private dependency installation, and Capacitor sync remain in your CI.

__CAPGO_KEEP_0__ 构建接收准备好的原生项目，用于编译您的应用。您的 web 源 __CAPGO_KEEP_1__、私有依赖安装和 __CAPGO_KEEP_2__ 同步仍然保留在您的 CI 中。

包含	描述
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/	构建缓存和IDE设置
.gradle/, .idea/, .swiftpm/	机密
.env(不包括)	Never uploaded

注意

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

您的责任

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

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

What Capgo Build Handles

• 在Capacitor中
• 在Capacitor中
• Code 使用您的凭据进行签名
• Optional App Store Connect 或 Google Play 提交
• 支持的本机构建配置和凭据值作为环境变量传递

Capgo 构建不需要访问您的私有 Nexus 注册表或 SSH 凭据，一旦您的 CI 准备了本机项目。请参阅 构建配置 支持的环境变量和存储选项。

对于通过 MDM 分发的 kiosk 风味，配置 Android 项目/构建以生成 APK。当请求构建时，使用两个标志跳过 Google Play 并检索签名输出：

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

--no-playstore-upload 防止 Play Store 上传，即使保存了 Play 凭据; --output-upload 提供对签名输出的有限期限链接。通过您的 MDM 分发该 APK。

下一步

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

• 配置iOS构建 - 设置证书和配置文件
• 配置Android构建 - 设置密钥库和Google Play商店
• 故障排除 上下文：支持/高级支持页面或底部支持部分。角色：部分或页面标题。见：页面support-policy.astro。消息键`support_policy_troubleshooting_title`（支持政策故障排除标题）。
• CLI Reference __CAPGO_KEEP_0__参考

- 完整命令文档

• 检查一下 故障排除指南
• 加入我们的 Discord 社区
• 通过电子邮件联系我们的支持团队 support@capgo.app