用 Capgo Cloud Build 在云端构建…

当需要用 Capgo 云端构建已签名的 iOS/Android 原生二进制（IPA/APK/AAB、TestFlight/App Store/Play 上传或临时下载链接）时使用。

适用场景

解决思路

1. 所有面向用户的命令统一使用 `npx @capgo/cli@latest`。
2. 把 API key、P12 密码、keystore 密码、App Store Connect 密钥、Play service account JSON 当作机密：新写的通用示例用占位符，但不要替换用户已提供的真实密钥值（除非用户明确要求），不要把密钥回显给用户，也不要在用户未明确要求时建议轮换密钥。
3. 优先使用 Capgo CLI 的构建流程，不要自创自定义 CI 脚本。
4. 先确认平台、app ID、项目路径、期望输出目标，以及用户是要上传商店还是只要临时下载链接。
5. 构建前检查：项目是 Capacitor 应用且存在目标平台原生目录（`ios/` 或 `android/`）；Capgo app 已存在（否则先运行 `npx @capgo/cli@latest app add com.example.app`）；API key 有触发原生构建的权限；签名凭证已存在或会在 `build request` 前创建/保存；输出目标明确（商店上传需 iOS 的 App Store Connect 凭证或 Android 的 Play 配置；仅下载链接用 `--output-upload`，可选 `--output-retention <duration>`）。
6. 登录方式：`npx @capgo/cli@latest login`（记住全局 key）、`npx @capgo/cli@latest login YOUR_API_KEY`、`npx @capgo/cli@latest login --local YOUR_API_KEY`（仅限本仓库，需确认 `.capgo` 已被 git 忽略）。
7. 构建命令的认证优先级：1) 命令上的 `-a, --apikey <apikey>`；2) `CAPGO_TOKEN` 环境变量；3) `login --local` 保存在 `.capgo` 的本地 key；4) `login` 保存在 `~/.capgo` 的全局 key。CI 用 `CAPGO_TOKEN`，单条可复制命令用 `-a, --apikey`。
8. iOS 首次云构建优先用交互式引导：`npx @capgo/cli@latest build init`（别名 `build onboarding`），无 key 时加 `-a YOUR_API_KEY`。它会验证 App Store Connect API key、创建或复用 Apple 签名资产、注册或复用 bundle ID、创建 App Store provisioning profile、把凭证保存到 `build request` 使用的本地存储、可在最后发起首次云构建，并把进度持久化到 `~/.capgo-credentials/onboarding/`、把恢复/支持材料保存到 `~/.capgo-credentials/support/`。
9. 用户已有 Apple 签名文件时手动保存 iOS 凭证：`npx @capgo/cli@latest build credentials save --appId com.example.app --platform ios --certificate ./cert.p12 --p12-password "P12_PASSWORD" --ios-provisioning-profile ./profile.mobileprovision --apple-key ./AuthKey_KEYID.p8 --apple-key-id "KEY_ID" --apple-issuer-id "ISSUER_UUID" --apple-team-id "TEAM_ID"`。
10. 有扩展或多 target 时重复 `--ios-provisioning-profile` 并按 bundle ID 映射：`--ios-provisioning-profile com.example.app=./App.mobileprovision --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision`。
11. iOS ad-hoc 构建：保存凭证时加 `--ios-distribution ad_hoc` 和 `--output-upload` 以收集 IPA。
12. 用户已有 Android 签名文件时手动保存：`npx @capgo/cli@latest build credentials save --appId com.example.app --platform android --keystore ./release.jks --keystore-alias "release-key" --keystore-key-password "KEY_PASSWORD" --keystore-store-password "STORE_PASSWORD" --play-config ./service-account.json`。
13. 只需 APK/AAB 下载链接、不上传 Play 时：保存凭证时加 `--output-upload` 并省略或覆盖 Play 上传。
14. Android 项目有多个 product flavor 时用 `--android-flavor <flavor>`。
15. 登录和凭证就绪后用 `build request [appId]` 发起构建：`npx @capgo/cli@latest build request com.example.app --platform ios --path .`（Android 同理）。
16. 常用 request 选项：`--platform ios|android`（必填）、`--path <path>`（默认当前目录）、`--build-mode debug|release`（默认 release）、`--ios-scheme <scheme>` 和 `--ios-target <target>`、`--ios-distribution app_store|ad_hoc`、`--android-flavor <flavor>`、`--output-upload`、`--output-retention <duration>`（`1h` 到 `7d`）、`--no-playstore-upload`（需配合 `--output-upload`）、`--skip-build-number-bump`、`--verbose`。
17. 示例：收集 iOS ad-hoc IPA 链接：`npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload --output-retention 2d`。
18. 示例：Android flavor 只要下载链接不上传 Play：`npx @capgo/cli@latest build request com.example.app --platform android --android-flavor production --output-upload --no-playstore-upload`。
19. 构建凭证默认全局存于 `~/.capgo-credentials/credentials.json`；加 `--local` 则用项目根目录的 `.capgo-credentials.json`。两个文件都绝不能提交到 git。
20. 列出脱敏后的已保存凭证：`npx @capgo/cli@latest build credentials list`（可加 `--appId com.example.app` 或 `--local`）。
21. 只更新变更字段：`npx @capgo/cli@latest build credentials update --appId com.example.app --platform ios --ios-provisioning-profile ./new-profile.mobileprovision`；Android 用 `--keystore ./new-release.jks`。
22. iOS provisioning profile 更新默认把新条目合并进现有映射；只有确实要整体替换时才用 `--overwrite-ios-provisioning-map`。
23. 迁移旧版 iOS provisioning 凭证：`npx @capgo/cli@latest build credentials migrate --appId com.example.app --platform ios`。
24. 仅在用户要删除时清除凭证：`npx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios` 或 `npx @capgo/cli@latest build credentials clear --local`。
25. CI 中优先用环境变量而非本地凭证文件，例如 iOS：`CAPGO_TOKEN`、`BUILD_CERTIFICATE_BASE64`、`P12_PASSWORD`、`APPLE_KEY_ID`、`APPLE_ISSUER_ID`、`APPLE_KEY_CONTENT`、`APP_STORE_CONNECT_TEAM_ID`、`CAPGO_IOS_PROVISIONING_MAP`，再运行 `npx @capgo/cli@latest build request com.example.app --platform ios`。
26. Android CI 常用：`CAPGO_TOKEN`、`ANDROID_KEYSTORE_FILE`、`KEYSTORE_KEY_ALIAS`、`KEYSTORE_KEY_PASSWORD`、`KEYSTORE_STORE_PASSWORD`、`PLAY_CONFIG_JSON` 或 `--output-upload`。使用仓库/CI 密钥存储，不要提交签名文件或生成的凭证 JSON。
27. 排错：`No Capgo API key found` → 运行 `login`、设置 `CAPGO_TOKEN` 或传 `-a YOUR_API_KEY`；`Insufficient permissions` → 确认 key 能访问该 app 且有原生构建权限；缺少输出目标 → 加商店上传凭证或启用 `--output-upload`；没有下载链接 → 用 `--output-upload` 请求或保存凭证，必要时设 `--output-retention`；iOS 签名失败 → 检查证书密码、Apple Team ID、分发模式和每个 bundle ID 到 provisioning profile 的映射；旧版 iOS provisioning profile 报错 → 运行 `build credentials migrate`；Android 签名失败 → 检查 keystore 路径、alias、key 密码、store 密码和 product flavor；要跳过 Play 上传 → `--output-upload --no-playstore-upload`；monorepo 路径不匹配 → 传 app 专属 `--path` 并尽量从 app 根目录运行；需要支持证据 → 用 `--verbose` 重跑失败命令。

适用边界 · 注意事项

• 不要用于仅 JavaScript 的 OTA 更新上传。
• 不要用于通用 CI/CD 搭建或本地原生构建（不涉及 Capgo Cloud Build 的场景）。
• 不要用于通用 Capacitor 配置，除非用户明确要求 Capgo 原生构建。