Capgo Native Builds 是一个用于在云端构建原生 iOS 和 Android 二进制的技能，主要面向希望由 Capgo 完成原生构建的开发者。
用途 当用户需要 Capgo Cloud Build、原生构建、已签名的 IPA/APK/AAB、TestFlight/App Store 构建、Play Store 构建或临时构建下载链接时使用本技能。它也适用于需要 Capgo CLI 登录、构建 API 密钥设置，或在 login、CAPGO_TOKEN 与 -a, --apikey 之间做选择的情况。此外，当用户需要 iOS 构建引导、Apple 签名设置、Android keystore 设置、Play 服务账号设置，或明确要求轮换凭据时，也可使用本技能。本技能不适用于仅 JavaScript 的 OTA 更新上传、通用 CI/CD 设置，或不涉及 Capgo Cloud Build 的本地原生构建。
主要能力 本技能覆盖以下能力：使用 npx @capgo/cli@latest 进行用户侧命令操作；处理 API 密钥、P12 密码、keystore 密码、App Store Connect 密钥和 Play 服务账号 JSON 等机密信息；优先采用 Capgo CLI 构建流程而非自定义 CI 脚本；确认平台、应用 ID、项目路径、期望输出目标以及用户是否需要商店上传或临时下载链接。凭据由 CLI 本地存储，仅在构建任务时发送给 Capgo，不会永久存储在 Capgo 服务器上，构建过程结束后即删除。
使用方式 在请求构建前，需验证项目是 Capacitor 应用并具备目标平台的原生文件夹（ios/ 或 android/），Capgo 应用已存在（如需要可先运行 npx @capgo/cli@latest app add com.example.app），用户拥有可触发原生构建的 Capgo API 密钥，签名凭据已存在或工作流会在构建请求前创建/保存它们，且输出目标明确。
认证与登录方面，可使用 npx @capgo/cli@latest login、npx @capgo/cli@latest login YOUR_API_KEY 或 npx @capgo/cli@latest login --local YOUR_API_KEY。构建命令的认证优先级为：命令上的 -a, --apikey；CAPGO_TOKEN 环境变量；login --local 保存在 .capgo 中的本地密钥；login 保存在 ~/.capgo 中的全局密钥。CI 密钥建议使用 CAPGO_TOKEN；创建单条可复制粘贴的命令用于引导或支持时使用 -a, --apikey；仅当密钥应限定在此仓库时使用 login --local，并确认 .capgo 已被 git 忽略。
推荐的构建流程包括：iOS 快速路径 build init（交互式引导命令，可验证 App Store Connect API 密钥、创建或复用 Apple 签名资产、注册或复用 bundle ID、创建 App Store 配置文件、保存构建凭据，并可在最后请求首次云构建）；手动 iOS 凭据保存（适用于已有 Apple 签名文件的情况，支持扩展或多目标时重复 --ios-provisioning-profile 并映射每个 bundle ID，ad-hoc 构建可设置分发模式并用 --output-upload 收集 IPA）；手动 Android 凭据保存（适用于已有 Android 签名文件的情况，仅需 APK/AAB 下载链接时可保存 --output-upload 并省略或覆盖 Play 上传，多产品风味时使用 --android-flavor <flavor>）。
请求构建使用 build request [appId]，常用选项包括 --platform ios|android（必需）、--path <path>、--build-mode debug|release（默认 release）、--ios-scheme 与 --ios-target、--ios-distribution app_store|ad_hoc、--android-flavor、--output-upload、--output-retention（1h 到 7d）、--no-playstore-upload（需配合 --output-upload）、--skip-build-number-bump 以及 --verbose。
凭据管理方面，构建凭据默认全局存储在 ~/.capgo-credentials/credentials.json，添加 --local 则使用项目根目录的 .capgo-credentials.json，两者均不可提交。可使用 build credentials list 列出脱敏的已保存凭据，使用 build credentials update 仅更新变更字段，使用 build credentials migrate 迁移旧版 iOS 配置文件凭据，使用 build credentials clear 清除凭据。
CI 指导方面，建议使用环境变量中的机密而非本地凭据文件。iOS CI 常用 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；Android CI 常用 CAPGO_TOKEN、ANDROID_KEYSTORE_FILE、KEYSTORE_KEY_ALIAS、KEYSTORE_KEY_PASSWORD、KEYSTORE_STORE_PASSWORD、PLAY_CONFIG_JSON 或 --output-upload。应使用仓库或 CI 机密存储，不要提交签名文件或生成的凭据 JSON。
适用场景 适用于需要云端原生 iOS/Android 构建、已签名安装包、商店上传或临时下载链接的 Capacitor 项目开发者，尤其是希望减少手动签名步骤、通过 CLI 统一管理构建与凭据的团队。
限制 本技能不适用于仅 JavaScript 的 OTA 更新上传、通用 CI/CD 设置或不涉及 Capgo Cloud Build 的本地原生构建。凭据不会永久存储在 Capgo 服务器上，构建完成后删除。使用前需满足 Capacitor 项目、原生文件夹、Capgo 应用、API 密钥权限和签名凭据等前置条件。故障排查涵盖无 API 密钥、权限不足、缺少输出目标、无下载链接、iOS 签名失败、旧版 iOS 配置文件错误、Android 签名失败、跳过 Play 上传、monorepo 路径不匹配以及需要支持证据等情形。