跳过内容
Capgo - 实时更新 Capacitor 应用程序 Capgo

配置选项

Cloud Build 配置选项的完整参考。使用此页面查找任何构建设置的CLI标志、环境变量或凭证密钥。

配置顺序

标题为“配置顺序”的部分

每个构建选项都可以用多种方式设置。当同一个选项在多个地方设置时，优先级更高的来源会获胜：

示例： 如果您保存的凭据有 SKIP_BUILD_NUMBER_BUMP=true 但是您传递 --no-skip-build-number-bump 在CLI上，CLI标志获胜，构建号将自动递增。

iOS选项

__CAPGO_KEEP_0__签名

Code Signing

Code 签名
CLI 标志环境变量凭证密钥默认描述
--build-certificate-base64 <cert>BUILD_CERTIFICATE_BASE64BUILD_CERTIFICATE_BASE64—Base64编码 .p12 分发证书
--ios-provisioning-profile <map>CAPGO_IOS_PROVISIONING_MAPCAPGO_IOS_PROVISIONING_MAP—作为应用程序 + 扩展的多目标应用程序的配置文件 path 或 bundleId=path 映射。支持多目标应用程序（应用程序 + 扩展）；配置文件名称将自动提取。
--p12-password <password>P12_PASSWORDP12_PASSWORD—应用程序的密码 .p12 如果证书没有密码，则省略证书

App Store Connect 认证

App Store Connect 认证
CLI 标志环境变量凭据密钥默认描述
--apple-key-id <id>APPLE_KEY_IDAPPLE_KEY_ID—App Store Connect API 密钥 ID
--apple-issuer-id <id>APPLE_ISSUER_IDAPPLE_ISSUER_ID—App Store Connect 发行者 ID (UUID)
--apple-key-content <content>APPLE_KEY_CONTENTAPPLE_KEY_CONTENT—Base64编码的 App Store Connect API 密钥 (.p8 文件)
--app-store-connect-team-id <id>APP_STORE_CONNECT_TEAM_IDAPP_STORE_CONNECT_TEAM_ID—App Store Connect Team ID
环境变量
CLI Flag默认值App Store Connect Team ID不推荐描述
--apple-id <email>FASTLANE_USERFASTLANE_USER—__CAPGO_KEEP_0__
--apple-app-specific-password <password>FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORDFASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD—应用程序专用密码（xxxx-xxxx-xxxx-xxxx)，在 appleid.apple.com
--apple-app-id <id>APPLE_APP_IDAPPLE_APP_ID—（例如 1234567890)

iOS 构建设置

标题为“iOS 构建设置”的部分
CLI 标志环境变量凭证密钥默认描述
--ios-scheme <scheme>CAPGO_IOS_SCHEMECAPGO_IOS_SCHEMEAppXcode 构建方案
--ios-target <target>CAPGO_IOS_TARGETCAPGO_IOS_TARGETAppXcode 构建目标（读取构建设置）
--ios-distribution <mode>CAPGO_IOS_DISTRIBUTIONCAPGO_IOS_DISTRIBUTIONapp_store发布模式： app_store 或 ad_hoc

Android 选项

Android 选项部分

Keystore 签名

密钥库签名
CLI 标志环境变量凭据密钥默认描述
--android-keystore-file <keystore>ANDROID_KEYSTORE_FILEANDROID_KEYSTORE_FILE—Base64编码的密钥库文件（.keystore 或 .jks)
--keystore-key-alias <alias>KEYSTORE_KEY_ALIASKEYSTORE_KEY_ALIASkey0密钥库密钥别名
--keystore-key-password <password>KEYSTORE_KEY_PASSWORDKEYSTORE_KEY_PASSWORD—密钥库密钥密码（如果未设置则回退到存储密码）
--keystore-store-password <password>KEYSTORE_STORE_PASSWORDKEYSTORE_STORE_PASSWORD—密钥库存储密码

Google Play 配置

Google Play 配置
CLI 标志环境变量凭据密钥默认描述
--play-config-json <json>PLAY_CONFIG_JSONPLAY_CONFIG_JSON—Base64编码的Google Play服务帐号JSON密钥
(仅环境)PLAY_STORE_TRACK—internalGoogle Play发布跟踪（internal, alpha, beta, production)
(仅环境)PLAY_STORE_RELEASE_STATUS—draft在选择的跟踪上发布的状态（draft, completed, inProgress, halted)

Android构建设置

Android 构建设置
CLI 标志默认描述
--android-flavor <flavor>—产品风味（例如 production). 必填 如果您的项目定义了多个风味，则需要此项。
--in-app-update-priority <0–5>—Google Play 内购更新优先级（更高=更紧急）。
--no-playstore-upload—构建和签名，但跳过 Play Store 上传（需要 --output-upload).

构建控制选项

构建控制选项

这些选项适用于 iOS 和 Android 构建。

Build Mode

Section titled “Build Mode”
CLI FlagDefaultDescription
--platform <platform>—Required. ios 或 android
--build-mode <mode>releasedebug 或 release
--path <path>.Project directory
--verbosefalseEnable verbose build logging
--ai-analyticsfalseOn build failure, send logs to Capgo AI for diagnosis — see 在构建失败时，将日志发送到__CAPGO_KEEP_0__ AI进行诊断 — 见

控制构建号

控制构建号
CLI 标志环境变量凭证密钥默认描述
--skip-build-number-bumpSKIP_BUILD_NUMBER_BUMPSKIP_BUILD_NUMBER_BUMPfalse跳过自动构建号/版本 code 自动递增
--no-skip-build-number-bump———显式重新启用自动递增（覆盖保存的凭证）

默认情况下，Capgo Cloud Build 将自动递增构建号：

  • iOS： 从 App Store Connect 获取最新的构建号，递增 1
  • Android: 从 Google Play 中获取最大值 versionCode 从 Google Play 中获取最大值，增加 1

当 --skip-build-number-bump 设置时，构建使用项目文件（Xcode 项目或）中的版本（Xcode 项目或 build.gradle).

输出上传

__CAPGO_KEEP_0__ 标志
CLI Flag凭据密钥默认描述Fetches max from Google Play, increments by 1
--output-uploadBUILD_OUTPUT_UPLOAD_ENABLEDBUILD_OUTPUT_UPLOAD_ENABLEDfalse将构建输出 (IPA/APK/AAB) 上传到 Capgo 存储。通过环境变量设置时使用 BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-uploadBUILD_OUTPUT_UPLOAD_ENABLED——禁用输出上传。通过环境变量设置时使用 BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>BUILD_OUTPUT_RETENTION_SECONDSBUILD_OUTPUT_RETENTION_SECONDS1h下载链接保持活跃的时间
--output-record <path>———在成功构建后，写入一个 JSON 记录 (任务 ID、状态、下载 URL、QR code) 到 <path> — 使用 build last-output.

保留格式： 使用人类可读的持续时间，如 1h, 6h, 2d, 7d. 最小值为 1 小时，最大值为 7 天。通过环境变量设置时使用秒数（例如 3600 认证

标题为“认证”

__CAPGO_KEEP_0__ 标志
CLI Flag环境变量默认描述
-a, --apikey <key>CAPGO_TOKEN—Capgo API用于身份验证的密钥
--supa-host <host>——自托管环境下自定义 Supabase 主机
--supa-anon <key>——自托管环境下自定义 Supabase anon 密钥

环境变量快速参考

环境变量快速参考

复制并粘贴到您的 CI/CD pipeline 中。所有变量都是可选的 — 只设置您需要的变量。

iOS

iOS
终端窗口
# Code signing (required for iOS builds)
BUILD_CERTIFICATE_BASE64="<base64-encoded .p12>"
CAPGO_IOS_PROVISIONING_MAP="<provisioning map generated by the CLI>"
P12_PASSWORD="<certificate password>"


# App Store Connect (required for store submission)
APPLE_KEY_ID="ABC1234567"
APPLE_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
APPLE_KEY_CONTENT="<base64-encoded .p8 key>"
APP_STORE_CONNECT_TEAM_ID="TEAM123456"


# Alternative to the App Store Connect API key above: Apple ID + app-specific
# password (e.g. when migrating from Ionic Appflow). All three are required.
# FASTLANE_USER="apple-id@example.com"
# FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
# APPLE_APP_ID="1234567890"


# Optional iOS settings
CAPGO_IOS_SCHEME="App"
CAPGO_IOS_TARGET="App"

Android

Android部分
终端窗口
# Keystore signing (required for Android builds)
ANDROID_KEYSTORE_FILE="<base64-encoded .keystore>"
KEYSTORE_KEY_ALIAS="my-key-alias"
KEYSTORE_KEY_PASSWORD="<key password>"
KEYSTORE_STORE_PASSWORD="<store password>"


# Google Play (required for store submission)
PLAY_CONFIG_JSON="<base64-encoded service account JSON>"


# Optional Android settings
PLAY_STORE_TRACK="internal"
PLAY_STORE_RELEASE_STATUS="draft"

构建控制

构建控制部分
终端窗口
# Build behavior
SKIP_BUILD_NUMBER_BUMP="true"          # Skip auto-increment
BUILD_OUTPUT_UPLOAD_ENABLED="true"     # Upload IPA/APK/AAB
BUILD_OUTPUT_RETENTION_SECONDS="3600"  # 1 hour download link


# Authentication
CAPGO_TOKEN="your-api-key"

凭证存储

凭证存储部分

保存凭证到本地

Section titled “本地保存凭据”

不必每次都传递标志或环境变量，仅需保存凭据一次：

终端窗口
# Save iOS credentials
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./dist_cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --p12-password "cert-password" \
  --apple-key ./AuthKey.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --apple-team-id TEAM123456


# Save Android credentials
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias my-key \
  --keystore-key-password "key-pass" \
  --keystore-store-password "store-pass" \
  --play-config ./play-service-account.json

存储位置

Section titled “存储位置”
标志位置用例
(默认)~/.capgo-credentials/credentials.json全局 — 机器上所有项目共享
--local.capgo-credentials.json 在项目根目录每个项目 — 覆盖全局配置时存在

凭据按 app ID （例如 com.example.myapp）进行键值对，一个凭据文件可以存储多个应用的设置而无冲突。每个应用的凭据进一步分为平台（ios / android).

管理已保存凭据

Section titled “Manage Saved Credentials”
终端窗口
# List saved credentials
bunx @capgo/cli@latest build credentials list


# Update a specific option without re-entering everything
bunx @capgo/cli@latest build credentials update --skip-build-number-bump


# Clear saved credentials
bunx @capgo/cli@latest build credentials clear --platform ios

示例

示例部分

GitHub 动作

GitHub 动作部分
name: Build and Submit
on:
  push:
    branches: [main]


jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx cap sync ios
      - run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}


  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx cap sync android
      - run: bunx @capgo/cli@latest build request --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

直接使用 CLI 参数

直接使用 CLI 参数部分
终端窗口
# Build iOS with all options inline
bunx @capgo/cli@latest build request \
  --platform ios \
  --build-mode release \
  --skip-build-number-bump \
  --output-retention 6h \
  --apikey YOUR_API_KEY


# Build Android, skip version bump, no output upload
bunx @capgo/cli@latest build request \
  --platform android \
  --skip-build-number-bump \
  --no-output-upload \
  --apikey YOUR_API_KEY

混合配置

混合配置

将保存的凭据与CLI覆盖项结合：

终端窗口
# Save base credentials once
bunx @capgo/cli@latest build credentials save --platform ios \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --output-upload


# Override specific options per-build
bunx @capgo/cli@latest build request --platform ios \
  --skip-build-number-bump \
  --output-retention 2d

CLI标志覆盖此特定运行的构建行为，而保存的凭据提供签名详细信息。