配置选项

所有 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 在 CLI 上，CLI 标志将生效，构建号将自动递增。

提示

对于 CI/CD 流水线，环境变量通常是最方便的方式。对于本地开发，保存的凭据（通过 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	—	描述文件作为 path 或 bundleId=path 映射。可重复用于多目标应用（应用 + 扩展）；描述文件名称会自动提取。
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	用于 .p12 证书的密码（如果证书没有密码，请省略）

App Store Connect 身份验证

CLI 标志	环境变量	凭据密钥	默认	描述
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API 密钥 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 编码的 App Store Connect API 密钥 (.p8 文件)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 团队 ID

不推荐

不建议使用 App-specific password 身份验证，也不推荐这种做法。 它只是为从 Ionic Appflow（曾依赖此方式）迁移的团队保留的兼容方案。它绑定个人 Apple ID，没有细粒度权限，无法查询 App Store Connect（因此构建号会回退为时间戳），而且只覆盖 TestFlight 上传本身。建议改用 App Store Connect API 密钥 (.p8)：这是 CI/CD 场景下更推荐、功能更强也更安全的选择。

应用专用密码认证（不推荐）

CLI 标志	环境变量	凭据密钥	默认	描述
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	拥有该应用的 Apple ID 账户邮箱
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	App 专用密码 (xxxx-xxxx-xxxx-xxxx) 生成于 appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	App Store Connect 的数字 App ID (例如 1234567890)

注意

这三个字段必须同时填写。数字 APPLE_APP_ID （可在 App Store Connect → 您的 App → App 信息 → Apple ID 中找到）是必填项：若缺失，fastlane 会回退到交互式 2FA 登录，而这在 build runner 上无法完成。使用此方法时，build number 会回退为基于时间戳的值，因为不会向 App Store Connect 查询最新 build number。

iOS 构建设置

CLI 标志	环境变量	凭据密钥	默认	描述
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	用于构建的 Xcode scheme
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	用于读取构建设置的 Xcode target
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	分发模式： app_store 或 ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	任意	使用此 Xcode 版本进行构建，例如 26, 26.0.1 或 27。主版本号可匹配任何次版本号。若无匹配版本，构建将快速失败并列出可用版本。

Xcode 27

使用 Xcode 27 (iOS 27 SDK) 进行构建，并配合 --xcode-version 27:

npx @capgo/cli@latest build request --platform ios --xcode-version 27

使用 iOS 27 SDK 构建的应用必须采用 UIScene 生命周期：如果没有 UIApplicationSceneManifest 中的 Info.plist 和场景代理，iOS 27 将在启动时停止应用。Capgo 会在构建开始前阻止这些构建（预扫描检查 ios/plist-scene-lifecycle-xcode27）。请添加 SceneDelegate 以及 UIApplicationSceneManifest 改为 ios/App/App/Info.plist，或者在添加之前继续使用 --xcode-version 26 进行构建。请参阅 Apple 的 场景生命周期指南.

CocoaPods 停止支持（2026 年 12 月）

Capgo Build 将于 2026 年 12 月停止构建使用 CocoaPods 的 iOS 项目。请在此之前将项目迁移到 Swift Package Manager：请参阅 Capacitor SPM 指南. 在此之前，CocoaPods 构建仍可正常工作；CLI 会打印警告，并通过 Capgo 向你的组织管理员发送提醒邮件。

---

Android 选项

Keystore 签名

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

Google Play 配置

CLI 标志	环境变量	凭据密钥	默认	描述
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64 编码的 Google Play 服务账号 JSON 密钥
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (或 production 配合 --submit-to-store-review)	Google Play 发布轨道（internal, alpha, beta, production）。从 CI 环境变量 / CLI 转发至构建运行器。
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (或 completed 配合 --submit-to-store-review)	所选轨道上的发布状态（draft, completed, inProgress, halted）。显式值会覆盖 --submit-to-store-review 默认值。

Android 构建设置

CLI 标志	默认	描述
--android-flavor <flavor>	—	要构建的 product flavor（例如 production). 必填 如果你的项目定义了多个 flavor。
--android-track <track>	internal	本次上传的 Google Play track。使用 --submit-to-store-review 且未设置 track 时，Capgo 默认为 production.
--android-release-status <status>	draft	Google Play 发布状态。使用 --submit-to-store-review 且未设置 status 时，Capgo 默认为 completed.
--in-app-update-priority <0–5>	—	本次发布的 Google Play 应用内更新优先级（越高越紧急）。
--no-playstore-upload	—	构建并签名，但跳过 Play Store 上传（需要 --output-upload).

---

构建控制选项

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

构建模式

CLI 标志	默认	描述
--platform <platform>	—	必填。 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 获取最新 build 编号，并加 1
• Android： 获取最大值 versionCode 从 Google Play 获取，并加 1

当 --skip-build-number-bump 已设置时，build 将使用项目文件（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 记录（job ID、状态、下载 URL、QR code）写入 <path> — 用以下命令读回 build last-output.

保留时长格式： 使用人类可读的时长，例如 1h, 6h, 2d, 7d。最小 1 小时，最大 7 天。通过环境变量设置时，使用秒数（例如 3600 表示 1 小时）。

构建缓存

Capgo 会保存编译后的原生产物（CocoaPods、Gradle 及相关构建输出） 每个应用 从而让重复构建启动得更快。 构建缓存默认已启用 针对每个应用。

CLI 标志	API 字段	默认	描述
--no-cache	cache_enabled: false	缓存开启	为此构建禁用缓存：跳过恢复 以及 不保存新条目
--cache-key <value>	cache_key	（省略）	分区缓存（例如 prod, staging）。省略则为每个应用使用一个共享的通用缓存

CLI 等效项： build request 接受 --no-cache 以及 --cache-key.

提示

使用不同的 --cache-key 值，当 RC 和生产构建共享同一应用 ID 但不得复用彼此的编译输出时——例如 --cache-key=prod 以及 --cache-key=staging.

CLI 示例：

# Default: restore/save the shared per-app cache
bunx @capgo/cli@latest build request com.example.app --platform android

# Separate caches per environment
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod

bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging

# One-off clean build (no restore, no save)
bunx @capgo/cli@latest build request com.example.app --platform ios --no-cache

API / webhook 负载 （当您的集成直接调用 Capgo Build 时）：

{
  "platform": "android",
  "cache_key": "prod"
}

省略 cache_key 用于共享通用缓存。设置 cache_key 以按环境分区。设置 "cache_enabled": false 以禁用单次请求的缓存（等同于 --no-cache).

如果构建看似成功但产物错误——或者在切换 RC 和生产环境后缺少 Android AAB——请尝试使用专用缓存键或一次性 --no-cache build。参见 故障排除：缓存恢复错误.

身份验证

CLI 标志	环境变量	默认	描述
-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>"
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"
CAPGO_IOS_XCODE_VERSION="27"

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"

---

凭据存储

本地保存凭据

无需每次传递 flags 或环境变量，只需保存一次凭据：

# 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

存储位置

参数	位置	使用场景
（默认）	~/.capgo-credentials/credentials.json	全局 — 共享于机器上的所有项目
--local	.capgo-credentials.json 位于项目根目录	按项目 — 当两者同时存在时覆盖全局配置

凭据以 应用 ID （例如 com.example.myapp作为键，因此单个凭据文件可以存储多个应用的设置而不会冲突。每个应用的凭据还会按平台进一步拆分（ios / android).

注意

添加 .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 标志

# 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 标志会覆盖此次特定运行的构建行为。