配置选项

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

配置顺序

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

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 但您传递 --no-skip-build-number-bump on the CLI, the CLI flag wins and build numbers will be auto-incremented.

提示

对于CI/CD管道，环境变量通常是最方便的。对于本地开发，通过（）保存的凭据（避免每次重复标志） build credentials save对于CI/CD管道，环境变量通常是最方便的。对于本地开发，通过（）保存的凭据（避免每次重复标志）

---

iOS 选项

Code 签名

CLI 标志	环境变量	凭据密钥	默认	描述
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64编码 .p12 分发证书
--build-provision-profile-base64 <profile>	BUILD_PROVISION_PROFILE_BASE64	BUILD_PROVISION_PROFILE_BASE64	—	Base64编码 .mobileprovision __CAPGO_KEEP_0__
--build-provision-profile-base64-prod <profile>	BUILD_PROVISION_PROFILE_BASE64_PROD	BUILD_PROVISION_PROFILE_BASE64_PROD	—	App Store 发行配置文件
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	用于 App Store 分发的生产配置文件（可选） .p12 用于

证书（如果证书没有密码，请忽略）

CLI Flag	__CAPGO_KEEP_0__ Flag	环境变量	凭证密钥	默认
--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 Issuer ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded App Store Connect API key (.p8 文件)
--apple-profile-name <name>	APPLE_PROFILE_NAME	APPLE_PROFILE_NAME	—	在 Apple Developer portal 中显示的分发配置文件名称
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect Team ID

注意

备用认证： 您也可以使用 Apple ID + app 特定密码代替 API 密钥。通过 --apple-id <email> 和 --apple-app-specific-password <password> (环境变量： APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD). API 密钥对于 CI/CD 建议使用

iOS 构建设置

CLI 标志	环境变量	凭证密钥	默认值	描述
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	用于构建的 Xcode 方案
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	用于读取构建设置的 Xcode 目标

---

Android 选项

Keystore 签名

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密钥

Android构建设置

环境变量	默认	描述
PLAY_STORE_TRACK	internal	Google Play 发布渠道 (internal, alpha, beta, production)
PLAY_STORE_RELEASE_STATUS	draft	Google Play 发布状态 (draft, completed)

---

构建控制选项

这两个选项都适用于 iOS 和 Android 构建。

构建模式

CLI Flag	描述	必填。
--platform <platform>	—	或 ios or android
--build-mode <mode>	release	debug 或 release
--build-config <json>	—	额外的 JSON 构建配置
--path <path>	.	项目目录
--verbose	false	启用详细的构建日志

构建号控制

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 当

设置时，构建将使用项目文件（Xcode 项目或 --skip-build-number-bump 输出上传 build.gradle).

标题为“输出上传”

CLI Flag	环境变量	凭证密钥	默认	描述
--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	下载链接保持活跃的时间

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

环境变量

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

---

环境变量快速参考

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

iOS

# Code signing (required for iOS builds)
BUILD_CERTIFICATE_BASE64="<base64-encoded .p12>"
BUILD_PROVISION_PROFILE_BASE64="<base64-encoded .mobileprovision>"
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>"
APPLE_PROFILE_NAME="My App Distribution Profile"
APP_STORE_CONNECT_TEAM_ID="TEAM123456"

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

安卓

# 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 build credentials save \
  --platform ios \
  --certificate ./dist_cert.p12 \
  --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-profile-name "My App Profile" \
  --apple-team-id TEAM123456

# Save Android credentials
bunx @capgo/cli 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

存储位置

标志	位置	用例
(默认)	~/.capgo-credentials/credentials.json	全局 — 共享所有机器上的项目
--local	.capgo-credentials.json 在项目根目录	按项目 — 覆盖全局配置

凭据是按 应用 ID (例如 com.example.myapp)，因此一个凭据文件可以存储多个应用的设置而无冲突。每个应用的凭据还分为平台（ios / android).

注意

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

管理保存的凭据

# List saved credentials
bunx @capgo/cli build credentials list

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

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

---

示例

GitHub Actions

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 build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.IOS_PROFILE }}
          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 }}
          APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
          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 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标志

# Build iOS with all options inline
bunx @capgo/cli 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 build request \
  --platform android \
  --skip-build-number-bump \
  --no-output-upload \
  --apikey YOUR_API_KEY

混合配置

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

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

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

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