capgo-native-builds

Capgo 原生构建

在 Capgo Cloud Build 上构建已签名的 iOS 和 Android 二进制文件，并将其交付到应用商店或临时下载链接。

以下信息已根据 @capgo/cli 8.77 和 https://capgo.app/docs/builder/ 核实（2026 年 10 月）。CLI 将原生云构建描述为“有限测试版”。

适用场景

在以下情况下使用：

• 用户请求 Capgo Cloud Build、云端原生构建、已签名的 IPA/APK/AAB、通过 Capgo 上传到 TestFlight、App Store 或 Play，或临时构建下载链接或二维码。
• 用户运行或询问 build init、build request、build prescan、build needed、build last-output、build sync-ios-version 或任何 build credentials ... 子命令。
• Capgo 构建在签名、预配、密钥库、预扫描或应用商店上传环节失败。

以下情况请勿使用：

• 仅更改 JavaScript/Web 资源。这属于 OTA 发布：使用 capgo-release-management；如需配置插件，则使用 capgo-live-updates。
• 用户在 Xcode 或 Gradle 中本地构建，或在自己的 CI 运行器上构建但未使用 Capgo Build。使用 capacitor-ci-cd。
• 用户需要准备应用商店页面、元数据或审核材料。使用 capacitor-app-store 和 capacitor-apple-review-preflight。
• 用户正在升级 Capacitor 本身。使用 capacitor-app-upgrades。

参考索引

仅在涉及相应主题时加载参考资料。

文件	加载时机
references/request-options.md	构建具体的 build request 标志：应用商店提交、轨道、发布说明、版本控制、缓存、Xcode 版本、预扫描标志
references/credentials-and-ci.md	保存、更新、导出或迁移凭据，以及将凭据写入 CI 密钥

密钥与确认

• 切勿要求用户将 Capgo API 密钥、签名密码、.p8 密钥、密钥库或服务帐号 JSON 粘贴到聊天中。请他们自行运行 npx @capgo/cli@latest login（该命令会打开浏览器或通过掩码提示输入密钥），或在 shell 或 CI 密钥存储中设置 CAPGO_TOKEN。
• 不要将密钥放在命令参数中：它们会留在 shell 历史记录和进程列表中。请使用环境变量、已保存的登录信息或 CLI 的交互式提示。
• 如果密钥仍出现在对话中，请勿复述或写入文件，并告知用户撤销该密钥并创建新密钥。
• npx @capgo/cli@latest 会从 npm 下载并运行最新的 CLI。仅在用户项目中运行，并事先征得用户同意。在 CI 中，请固定使用确切版本。
• 对任何会更改远程状态的命令，务必先征求同意：上传 bundle、更改或推广渠道、删除应用、bundle、渠道或密钥、请求上传到应用商店的构建，以及导出或删除凭据。请说明将对哪个应用和渠道进行何种更改。

操作规则

• 面向用户的命令中请使用 npx @capgo/cli@latest。
• API 密钥、P12 密码、密钥库密码、.p8 密钥和 Play 服务帐号 JSON 均为密钥。示例中请使用占位符。切勿在聊天中索要这些信息，也切勿原样复述。如果用户将其粘贴到聊天中，请告知用户撤销该密钥并创建新密钥。
• 凭据保存在本地（~/.capgo-credentials/credentials.json，或使用 --local 时保存在 .capgo-credentials.json）。凭据仅会在构建任务期间上传，构建完成后会删除服务器上的临时副本。切勿提交这两个文件。
• 请求构建前，请确认以下信息：平台、应用 ID、项目路径、flavor 或 scheme，以及目标位置（上传到应用商店、下载链接或两者兼有）。

身份验证与 API 密钥优先级

CLI 按以下顺序解析密钥：

1. 命令中的 -a, --apikey <key>
2. CAPGO_TOKEN 环境变量
3. ~/.capgo，由 npx @capgo/cli@latest login 保存的全局密钥
4. ./.capgo，由 login --local 保存的项目密钥

注意：全局密钥优先于项目本地密钥。如果仓库必须使用其他组织的密钥，请设置 CAPGO_TOKEN。确保 .capgo 已添加到 Git 忽略规则中。

操作流程

1. 检查

• 运行 ls ios android，确认目标原生目录存在，并且已运行 npx cap sync <platform>。
• 查看 capacitor.config.* 中的 appId。它必须与 iOS bundle ID 和 Android applicationId 一致（预扫描检查项为 shared/bundle-id-consistency）。
• iOS：检查 Xcode 方案和目标名称（默认为 App），以及需要单独配置预配描述文件的扩展。
• Android：检查 android/app/build.gradle 中的 productFlavors。如果有多个 flavor，则必须指定 --android-flavor。
• 检查应用是否已存在：npx @capgo/cli@latest app list。使用 npx @capgo/cli@latest app add com.example.app 添加应用。

2. 判断是否需要原生构建

npx @capgo/cli@latest build needed com.example.app --channel production
# prints "yes" and exits 1 -> native build required
# prints "no" and exits 0 -> ship OTA instead
# exits 2 -> the command itself failed

它只比较原生软件包元数据。直接修改 ios/ 或 android/ 下的内容仍需要原生构建。

3. 设置凭据

首次构建时使用交互模式（推荐）：

npx @capgo/cli@latest build init        # alias: build onboarding

• iOS：验证或创建 App Store Connect API 密钥，然后创建或复用证书、bundle ID 和 App Store 预配描述文件。所有内容都会保存到本地，并可立即启动首次构建。进度会保存在 ~/.capgo-credentials/onboarding/ 下，方便用户稍后继续。
• Android：设置密钥库。之后通过 Google OAuth 配置 GCP 服务账号，并发送 Play Console 邀请。
• 用于处理 .p8 密钥的 macOS 助手：npx @capgo/cli@latest build credentials apple-key --appId com.example.app。

如果用户已有签名文件，请改用 build credentials save。参阅 references/credentials-and-ci.md。

4. 构建前检查

npx @capgo/cli@latest build prescan com.example.app --platform ios

build request 会自动运行预扫描。可单独运行预扫描，在上传任何内容前修复问题。如果某项发现是有意为之，只跳过对应检查：--prescan-skip <check-id>。避免使用 --no-prescan。

5. 请求构建

# App Store / TestFlight (default ios distribution app_store)
npx @capgo/cli@latest build request com.example.app --platform ios --path .

# Android to Play internal track (default track internal, status draft)
npx @capgo/cli@latest build request com.example.app --platform android --path .

# Artifact only, no store upload
npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload --output-retention 2d
npx @capgo/cli@latest build request com.example.app --platform android --no-playstore-upload --output-upload

--output-retention 的取值范围为 1h 至 7d。凭据中保存的默认 TTL 为 1h。

注意事项

• Xcode / Capacitor 9： Capgo Build 文档列出的环境为 macOS Tahoe 26.2 和 Xcode 26.2。可以使用 --xcode-version <major[.minor]>（或 CAPGO_IOS_XCODE_VERSION）指定版本。Capacitor 9 需要 Xcode 27+。Capgo 文档和 CLI 8.77 并未确认有 Xcode 27 构建器。承诺支持 Capacitor 9 iOS 云构建前，请使用 --xcode-version 27 或查阅最新文档确认。
• --no-playstore-upload 必须与 --output-upload 一起使用。否则构建没有目标位置。
• iOS ad hoc 构建会跳过商店。App Store 记录尚不存在时，请将其与 --output-upload 一起使用。
• --submit-to-store-review 会将 Android 默认设置改为 production 跟踪渠道，状态设为 completed。添加该选项前，请先与用户确认。
• 构建号默认自动递增。如果项目自行管理构建号，请添加 --skip-build-number-bump。营销版本也可以自动递增（--skip-marketing-version-bump 可关闭此功能）。
• 构建超时默认为 15 分钟。可使用 npx @capgo/cli@latest app set com.example.app --build-timeout-minutes 60 延长（范围为 5 至 360）。
• capacitor.config 中保留了 server.url（实时重载）会导致商店构建的预扫描检查 ios/capacitor-server-url-shipped 失败。请移除该配置，而不是跳过检查。

验证

1. npx @capgo/cli@latest build credentials list --appId com.example.app 会显示目标平台的已屏蔽凭据。
2. npx @capgo/cli@latest build prescan com.example.app --platform <p> --fail-on-warnings 以状态码 0 退出。
3. build request 以成功状态结束。使用 --output-upload 时，会输出下载链接和二维码。使用 --output-record /tmp/build.json 时，请检查 npx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl。
4. 商店发布流程：构建会显示在 TestFlight 或所选的 Play Console 跟踪渠道中。
5. 将构建产物安装到设备上，并检查版本和构建号。

错误处理

字符串 / 症状	修复方法
No Capgo API key found. Run ... first, then retry this command.	用户运行 npx @capgo/cli@latest login，或设置 CAPGO_TOKEN
Insufficient permissions for <key> / prescan shared/apikey-permission	此密钥的角色无权为此应用或组织请求原生构建。请使用具有构建权限的密钥
Missing required argument: --platform <ios|android>	添加 --platform ios 或 --platform android
❌ No credentials found for this app and platform	运行 build init 或 build credentials save --appId <id> --platform <p> ...。检查使用的是 --local 还是全局存储
Legacy provisioning profile format detected. Run: npx @capgo/cli build credentials migrate --platform ios	运行 npx @capgo/cli@latest build credentials migrate --platform ios
Missing argument, you need to provide a appId, or be in a capacitor project	按位置传入应用 ID，或从应用根目录运行
output-retention must be a number with optional unit: s, m, h, d	使用 1h、6h、2d 等（最长 7d）
Prescan ios/cert-profile-pairing / ios/profile-type-vs-mode	配置文件未嵌入证书，或与 app_store/ad_hoc 不匹配。使用 build credentials ios-provisioning 重新生成
Prescan ios/targets-covered	某个扩展没有配置文件。添加 --ios-provisioning-profile <bundleId>=<path>
Android “Key alias not found” / 密码错误	检查别名和密码。如果二者不同，请同时传入 --keystore-key-password 和 --keystore-store-password
多个 flavor 错误	添加 --android-flavor <flavor>
需要诊断	使用 --verbose 重新运行。--ai-analytics 会将失败日志发送给 Capgo AI。--send-logs-to-support 会将日志发送给支持团队

更多修复方法：https://capgo.app/docs/builder/troubleshooting/

支持文档

• 构建参考：https://capgo.app/docs/cli/reference/build/
• 入门指南：https://capgo.app/docs/builder/getting-started/
• iOS：https://capgo.app/docs/builder/ios/ · Android：https://capgo.app/docs/builder/android/
• 凭据：https://capgo.app/docs/builder/credentials/ · 预检：https://capgo.app/docs/builder/prescan/
• CI 中的 OTA 与原生构建：https://capgo.app/docs/builder/ci-ota-or-native/