配置选项

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

配置顺序

配置顺序：__CAPGO_KEEP_0__标志覆盖环境变量，环境变量覆盖本地凭据，后者覆盖全局凭据

flowchart LR
    A["🔧 CLI Flag"] -->|overrides| B["🌍 Environment Variable"]
    B -->|overrides| C["📁 Local Credentials"]
    C -->|overrides| D["🏠 Global Credentials"]
    style A fill:#6366f1,color:#fff,stroke:#4f46e5
    style B fill:#8b5cf6,color:#fff,stroke:#7c3aed
    style C fill:#a78bfa,color:#fff,stroke:#8b5cf6
    style D fill:#c4b5fd,color:#1e1b4b,stroke:#a78bfa

如果您保存的凭据有 但是您传递 SKIP_BUILD_NUMBER_BUMP=true 在__CAPGO_KEEP_0__标志上，__CAPGO_KEEP_1__标志获胜，构建号将自动递增。 --no-skip-build-number-bump on the CLI, the CLI flag wins and build numbers will be auto-incremented.

对于CI/CD管道，环境变量通常是最方便的。对于本地开发，保存的凭据（通过

Configuration Precedence build credentials save避免每次都重复标志。

---

iOS 选项

Code 签名

CLI 标志	环境变量	凭据密钥	默认	描述
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64编码 .p12 分布式证书
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	Provisioning profile as a path or bundleId=path mapping. Repeatable for multi-target apps (app + extensions); the profile name is auto-extracted.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Password for the .p12 certificate (omit if certificate has no password)

App Store Connect Authentication

CLI Flag	Env Variable	Credential Key	Default	Description
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API Key ID
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect 发行者 ID（UUID）
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded App Store Connect API key（.p8 文件）
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 团队 ID

不推荐

建议不要使用 App Store Connect 团队 ID 进行认证，因为它存在安全风险。 它仅作为 Ionic Appflow 迁移的兼容性路径存在。它与个人 Apple ID 关联，没有细粒度权限，无法查询 App Store Connect（因此构建号会回退到时间戳），仅用于 TestFlight 上传本身。请使用 App Store Connect API key（.p8)，它是推荐的、更强大的、更安全的 CI/CD 选项。

App Store Connect 团队 ID 认证（不推荐）

CLI Flag	环境变量	凭据密钥	默认	描述
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	应用所有者的Apple ID邮箱
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	应用专用密码（xxxx-xxxx-xxxx-xxxx）在 appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	数字App Store Connect应用ID（例如 1234567890)

注意

所有三个字段都需要一起填写。数字 APPLE_APP_ID (在 App Store Connect → 你的应用 → 应用信息 → Apple ID) 中必填：如果没有它，fastlane 将回退到一个交互式 2FA 登录，无法在构建运行器上完成。当使用此方法时，构建号将回退到一个基于时间戳的值，因为 App Store Connect 不会为最新的构建号进行查询。

iOS 构建设置

CLI 标志	环境变量	凭据密钥	默认	描述
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode 构建方案
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode 构建目标
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	发布模式： app_store 或 ad_hoc

---

安卓选项

密钥库签名

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

Google Play 配置

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

Android 构建设置

CLI 标志	默认	描述
--android-flavor <flavor>	—	构建的产品风味 (例如 production). 必填 如果您的项目定义了多个风味。
--in-app-update-priority <0–5>	—	Google Play 内购更新优先级 (更高 = 更紧急)
--no-playstore-upload	—	Build and sign, but skip the Play Store upload (requires --output-upload).

---

Build Control Options

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

Build Mode

CLI Flag	Default	Description
--platform <platform>	—	Required. ios 或 android
--build-mode <mode>	release	debug 或 release
--path <path>	.	项目目录
--verbose	false	启用详细构建日志
--ai-analytics	false	构建失败时，发送日志到Capgo AI 进行诊断 — 见 AI 构建诊断

构建号控制

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

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

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

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

输出上传

CLI 标志	环境变量	凭证密钥	默认	描述
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	上传构建输出（IPA/APK/AAB）到Capgo存储中。当通过环境变量设置时，使用 BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	禁用输出上传。当通过环境变量设置时，使用 BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	下载链接保持活动时间
--output-record <path>	—	—	—	成功构建后，写入一个JSON记录（任务ID、状态、下载URL、QRcode）到 <path> —通过 build last-output.

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

认证

CLI Flag	环境变量	默认	描述
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API 认证密钥
--supa-host <host>	—	—	自建 Supabase 主机（仅限自建）
--supa-anon <key>	—	—	自建 Supabase 匿名密钥（仅限自建）

---

环境变量快速参考

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

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

# 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"

---

凭证存储

保存凭证本地

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

# 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

存储位置

标志	位置	Use Case
(default)	~/.capgo-credentials/credentials.json	Global — shared across all projects on your machine
--local	.capgo-credentials.json in project root	Per-project — overrides global when both exist

Credentials are keyed by app ID (e.g. com.example.myapp), so a single credentials file can store settings for multiple apps without conflicts. Each app’s credentials are further split by platform (ios / android).

Caution

Add .capgo-credentials.json 到你的 .gitignore 如果使用本地凭证。永远不要将凭证提交到版本控制中。

管理保存的凭证

# 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 动作

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 flags 直接

# 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 参数覆盖此特定运行的构建行为。