🔹 构建

🏗️ 通过 Capgo 云管理原生 iOS/Android 构建

构建访问和输出

原生云构建请求目前处于有限 beta 阶段，访问受限。构建凭据永远不会存储在 Capgo 服务器上：它们只用于构建，然后删除。构建输出可选上传时间有限的下载链接。

先保存凭据

npx @capgo/cli build credentials save --appId YOUR_APP_ID --platform ios
npx @capgo/cli build credentials save --appId YOUR_APP_ID --platform android

在 CI 中捕获输出 URL

传递 --output-record 以持久化下载 URL 和 QR code,然后使用 build last-output 以读取它：

npx @capgo/cli build request APP_ID --platform android --output-upload --output-record /tmp/build.json
npx @capgo/cli build last-output --path /tmp/build.json --field outputUrl

🔹 所需

npx @capgo/cli@latest build needed

🧭 如果需要原生构建，则打印“yes”并使用 code 1 退出；否则打印“no”并使用 code 0 退出。命令失败使用 code 2 退出。

示例：

npx @capgo/cli@latest build needed com.example.app --channel production --verbose

选项：

参数	类型	描述
-a	string	API 的密钥用于链接到您的帐户
-c	string	与 CapacitorUpdater.defaultChannel 或公共默认频道进行比较的频道
—package-json	string	多包仓库的package.json文件路径（逗号分隔）
—node-modules	string	多包仓库的node_modules目录路径（逗号分隔）
—verbose	boolean	启用详细日志的verbose输出
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—supa-anon	string	自主托管的自定义 Supabase 匿名密钥

🚀 初始化

别名： onboarding

npx @capgo/cli@latest build init

交互式设置构建凭据（iOS：自动证书和配置文件；Android：自动keystore和Google OAuth配置GCP服务账户和Play Console邀请）

选项：

参数	类型	描述
-a	string	API
用于链接到您的帐户的密钥	string	平台（ios或android）进行上线。如果省略，仅当存在一个本地文件夹时才会自动检测；否则会提示。
——supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
——no-analytics	boolean	关闭此次构建的 onboard 分析和终端回放

🔹 请求

npx @capgo/cli@latest build request

Request a native build from Capgo Cloud. This command will zip your project directory and upload it to Capgo for building. The build will be processed and sent directly to app stores. Credentials are never stored on Capgo servers; they are deleted after the build. Save them before requesting a build:

npx @capgo/cli build credentials save --appId APP_ID --platform ios

示例：

npx @capgo/cli@latest build request com.example.app --platform ios --path .

选项：

参数	类型	描述
—path	string	项目目录的路径（默认：当前目录）
—node-modules	string	多包项目的node_modules目录路径（逗号分隔）
—platform	string	目标平台：ios 或 android (必填)
—build-mode	string	构建模式：debug 或 release (默认：release)
—build-certificate-base64	string	iOS：Base64编码的 .p12 证书
—p12-password	string	iOS：证书密码（如果证书没有密码，则可选）
—apple-id	string	iOS：用于上传 App Store Connect 应用程序特定密码的 Apple ID 电子邮件（替代 App Store Connect API 密钥）
—apple-app-specific-password	string	iOS：用于 TestFlight 上传的 App 特定密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	string	iOS: 必须与 —apple-id 和 —apple-app-specific-password 一起使用的数字 App Store Connect 应用 ID
—apple-key-id	string	iOS: App Store Connect API 密钥 ID
—apple-issuer-id	string	iOS: App Store Connect 发行者 ID
—apple-key-content	string	iOS: App Store Connect API 密钥 (.p8) 的 Base64 编码
—app-store-connect-team-id	string	iOS: App Store Connect 团队 ID
—ios-scheme	string	iOS: Xcode 构建方案 (默认: App)
—ios-target	string	iOS: Xcode target for reading build settings (default: same as scheme)
—中海存为图统计	string	iOS: 存为统计形常
—中海存为统计形常主	string	iOS: 存为统计形常主结定中形常
—张东存为统计形常主结定中形常	string	Android: 存为统计形常主结定中形常
Android: 统计形常主名稱	string	Android: 统计形常主密语
Android: 统计形常主密语	string	Android: 统计形常主结定密
Android: 统计形常主结定密	string	Android: Keystore 密钥库存储密码
—play-config-json	string	Android: 基于Base64的Google Play服务账户JSON
—android-flavor	string	Android: 构建的产品风味（例如生产环境）。如果您的项目有多个风味，则必填。
—android-track	string	Android: 上传到Google Play的跟踪（内部、alpha、beta、生产）。如果没有—submit-to-store-review，则默认为内部。如果有—submit-to-store-review但没有设置跟踪，则默认为生产。优先级：CLI > env > 保存的凭据
—android-release-status	string	Android: 上传到Google Play的发布状态（草稿、已完成、进行中、已暂停）。如果没有—submit-to-store-review，则默认为草稿。如果有—submit-to-store-review但没有设置状态，则默认为已完成。优先级：CLI > env > 保存的凭据
—in-app-update-priority	string	Android: Google Play内应用更新的优先级（整数0-5；越高越紧急）。请参见 https://developer.android.com/guide/playcore/in-app-updates。优先级：CLI > env > 保存的凭据
—不上传Google Play	boolean	跳过此构建的Google Play Store上传（清除保存的Play配置）。需要—输出上传。
—提交到商店审核	boolean	上传后，提交商店发布进行审核，而不是将其留作草稿/未激活的构建。 在Android上，这默认为生产跟踪，release_status完成（使用—android-track / PLAY_STORE_TRACK和—android-release-status / PLAY_STORE_RELEASE_STATUS进行覆盖）。 在iOS上，这将处理的TestFlight构建提交到App Store审核。
—商店发布名称	string	商店发布名称/版本标签。 Android将其发送为Google Play版本名称； iOS在创建或重用可编辑版本时使用它作为App Store版本。
—商店发布说明	string	默认商店发布说明。 Android使用此作为Play更改日志； iOS使用它作为fallback App Store What’s New文本。
—商店发布说明语言	string	本地化商店发布说明（可重复），例如—商店发布说明语言 en-US=“Bug fixes” —商店发布说明语言 fr-FR=“Corrections”。
—iOS TestFlight 组	string	iOS: 可选的,逗号分隔的 TestFlight 外部组名称或 ID,用于外部 beta 分发。
——ios-automatic-release	boolean	iOS: 自动在 Apple 批准后发布 App Store 版本。默认为手动发布。
——no-ios-automatic-release	boolean	iOS: 在 Apple 批准后保持 App Store 版本等待手动发布。
——output-upload	boolean	仅此次构建覆盖输出上传行为 (启用)。优先级: CLI > env > 保存的凭证
——no-output-upload	boolean	仅此次构建覆盖输出上传行为 (禁用)。优先级: CLI > env > 保存的凭证
——output-retention	string	仅此次构建覆盖输出链接 TTL (1h 到 7d)。示例: 1h, 6h, 2d。优先级: CLI > env > 保存的凭证
——output-record	string	在成功构建后，写入一个 JSON 记录（jobId，状态，输出 URL，QR 码 ASCII，QR 码 PNG 路径，完成时间）到一个路径。一个 PNG QR code 也会写入到该路径旁边带有后缀。 .qr.png 读取字段回 build last-output.
—no-skip-build-number-bump	boolean	覆盖保存的凭据以重新启用此构建的自动构建号递增。
—skip-marketing-version-bump	boolean	跳过自动市场版本（CFBundleShortVersionString / versionName）递增，当应用程序已经发布时。
—sync-ios-version	boolean	iOS：在上传项目之前，从 package.json 中同步 Xcode MARKETING_VERSION。
—ai-analytics	boolean	在构建失败时，发送日志到 Capgo AI 进行诊断。在交互式终端中，这跳过了前置确认；在 CI 中，这自动上传并在 stderr 中打印分析结果。
—no-prescan	boolean	跳过自动预构建扫描
———忽略致命错误的扫描	boolean	运行预构建扫描，但永远不会阻塞构建（仅报告）
———忽略扫描	string	跳过特定扫描检查（通过 ID 重复或逗号分隔）。其他检查仍然运行。
———警告扫描	string	将特定扫描检查（通过 ID 重复或逗号分隔）降级为警告。检查仍然运行。
———在警告时失败	boolean	将预扫描警告视为致命错误
———将日志发送到支持	boolean	在 CI/CD 构建失败时，自动上传构建日志到Capgo支持（无需电子邮件）。Capgo支持将收到电子邮件通知并会通过电子邮件跟进。与 —ai-analytics 相加。
———发送日志	boolean	———发送日志（已弃用）
-a	string	API key to link to your account
—supa-host	string	自定义 Supabase 主机 URL（适用于自主托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase 匿名密钥（适用于自主托管）
—verbose	boolean	启用详细日志的verbose输出

🔹 Sync-ios-version

npx @capgo/cli@latest build sync-ios-version

同步本地 iOS Xcode MARKETING_VERSION 从 package.json。

示例：

npx @capgo/cli@latest build sync-ios-version --path .

选项：

参数	类型	描述
—path	string	项目目录的路径（默认：当前目录）
—check	boolean	仅检查；当 MARKETING_VERSION 不一致时退出非零

🔹 预扫描

npx @capgo/cli@latest build prescan

在上传任何内容之前，扫描您的项目和保存的凭据以查找可能会导致云构建失败的问题。检查凭据（过期、密码、配置文件配对）、项目状态（cap sync、node_modules布局）和平台配置。它将自动在 build request;此命令将其独立运行（例如在CI中）。 查看 预扫描检查 --skip / --warn 查看完整的检查目录和如何

个别规则。

选项：	参数	简介
—平台	string	目标平台：ios 或 android（必填）
—路径	string	项目目录路径（默认：当前目录）
-a	string	API
—android-flavor	string	Android：构建使用的产品风格
—ios-dist	string	iOS：用于验证的分发模式
—json	boolean	输出机器可读的 JSON 报告
__CAPGO_KEEP_0__	boolean	在 CI 环境下遇到警告时退出非零状态
诊断模式：报告所有信息但总是退出 0	boolean	跳过特定检查（可重复或用逗号分隔）
将特定检查（可重复或用逗号分隔）降级为警告	string	详细日志输出
__CAPGO_KEEP_0__	string	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	boolean	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	string	Custom Supabase host URL (for self-hosting or Capgo development)
——supa-anon	string	自定义 Supabase 匿名密钥（用于自主托管）

🔹 最后输出

npx @capgo/cli@latest build last-output

读取之前写入的构建输出记录 build request --output-record. 默认打印完整的 JSON，使用 —field 打印单个字段，或者使用 —qr 打印 ASCII QR code。在 CI 中有用，用于获取下载 URL 或 QR 并将其发布到 PR 或问题中。 示例: npx @capgo/cli build last-output —path /tmp/build.json npx @capgo/cli build last-output —path /tmp/build.json —field outputUrl npx @capgo/cli build last-output —path /tmp/build.json —qr

选项：

参数	类型	描述
—path	string	路径（必填）
—field	string	打印单个字段（可选值：jobId, appId, platform, buildMode, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt, schemaVersion）
—qr	boolean	打印渲染的ASCII QR code（—field qrCodeAscii的快捷方式）

🔹 凭据

安全提示：

• 凭据保存在~/.capgo-credentials/credentials.json（全局）或.capgo-credentials.json（本地）
• 在构建时发送到Capgo，但永远不会永久存储
• 立即在构建后从 Capgo 中删除
• 构建输出可选地可上传以获取有限期下载链接 📚 文档: iOS 配置: https://capgo.app/docs/cli/cloud-build/ios/ Android 配置: https://capgo.app/docs/cli/cloud-build/android/

🔹 Apple-key

别名： asc-key

npx @capgo/cli@latest build credentials apple-key

创建一个 App Store Connect 团队 API 密钥，使用一个带有 macOS 助手的指导程序（仅限 macOS）。 打开一个本机窗口，通过嵌入式浏览器走你通过 Apple 的 App Store Connect UI，自动捕获 Issuer ID + Key ID，拦截一次性的 .p8，验证它与 Apple，保存到 ~/.appstoreconnect/private_keys。 进度统计信息将传递给 Capgo 分析 (通过 CAPGO_DISABLE_TELEMETRY 禁用)。 npx @capgo/cli 构建凭据 apple-key —appId com.example.app

示例：

Example:

选项:

参数	类型	描述
-a	string	API 键用于链接到您的帐户
—appId	string	将捕获的密钥保存到此 iOS 构建凭据中
—local	boolean	将密钥保存到项目级别的 .capgo-credentials.json 文件中而不是全局文件
——json	boolean	打印捕获的密钥 ID / 发行者 ID / .p8 路径作为 JSON

🔹 保存

npx @capgo/cli@latest build credentials save

为 iOS 或 Android 保存构建凭据。 凭据存储在:

• ~/.capgo-凭据/凭据.json (默认，全球)
• .capgo-凭据.json 在项目根目录 (使用 —local 标志) ⚠️ 必须在请求构建之前保存凭据。 🔒 这些凭据永远不会在Capgo服务器永久存储。 它们在构建完成后立即删除。 📚 配置指南: • iOS: https://capgo.app/docs/cli/cloud-build/ios/ • Android: https://capgo.app/docs/cli/cloud-build/android/ npx @capgo/cli build credentials save —platform ios
  —certificate ./cert.p12 —p12-password “password”
  —ios-provisioning-profile ./profile.mobileprovision
  —apple-key ./AuthKey.p8 —apple-key-id “KEY123”
  —apple-issuer-id “issuer-uuid” —apple-team-id “team-id” Multi-target Example (app + widget extension): npx @capgo/cli build credentials save —platform ios
  —ios-provisioning-profile ./App.mobileprovision
  —ios-provisioning-profile com.example.widget=./Widget.mobileprovision
  … npx @capgo/cli build credentials save —platform android
  —keystore ./release.keystore —keystore-alias “my-key”
  —keystore-key-password “key-pass”
  —play-config ./service-account.json Local storage (per-project): npx @capgo/cli build credentials save —local —platform ios …

Example:

iOS Example:

选项:

参数	类型	描述
—appId	string	应用 ID（例如，com.example.app）(必填)
—platform	string	平台：ios 或 android (必填)
—certificate	string	iOS：.p12 证书文件路径
—ios-配置文件	string	iOS: 配置文件路径或bundleId=path（可重复）
—p12-密码	string	iOS: 证书密码（如果证书没有密码，则可选）
—apple-密钥	string	iOS: .p8 App Store Connect API 密钥路径
—apple-密钥ID	string	iOS: App Store Connect API 密钥ID
—apple-发行者ID	string	iOS: App Store Connect 发行者ID
—apple-团队ID	string	iOS: App Store Connect 团队ID
—ios-发布	string	iOS: 发布模式
—apple-id	string	iOS: App Store Connect 的 Apple ID 邮箱（用于替代 App Store Connect API 密钥）
—apple-app-specific-password	string	iOS: TestFlight 上传的 App-specific 密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	string	iOS: App Store Connect 的数字应用 ID（需要与 —apple-id 和 —apple-app-specific-password 一起使用）
—keystore	string	Android: Keystore 文件路径 (.keystore 或 .jks)
—keystore-alias	string	Android: Keystore 密钥别名
——密钥库密钥密码	string	Android: 密钥库密钥密码
——密钥库存储密码	string	Android: 密钥库存储密码
——Play配置	string	Android: Play商店服务账户 JSON 文件路径
——Android风味	string	Android: 构建的产品风味（例如生产环境）。如果项目有多个风味，则必填
——应用内更新优先级	string	Android: Google Play 应用内更新的优先级（整数 0–5；越高越紧急）。省略则保持原有值
——本地	boolean	将凭据保存到项目根目录下的 .capgo-credentials.json 文件而不是全局 ~/.capgo-credentials/
——输出上传	boolean	上传构建输出（IPA/APK/AAB）到Capgo存储并打印下载链接
——不输出上传	boolean	不上传构建输出（IPA/APK/AAB）到Capgo存储
——输出保留	string	输出链接有效期：1小时到7天（默认：1小时）。示例：1小时，6小时，2天
——跳过构建号码增加	boolean	跳过自动构建号码/版本code增加
——不跳过构建号码增加	boolean	重新启用自动构建号码增加（默认行为）
——跳过市场版本号码增加	boolean	跳过自动市场版本号码增加（当应用已发布时）
—no-skip-marketing-version-bump	boolean	重新启用自动市场版本更新 (默认行为)

📋 列表

npx @capgo/cli@latest build credentials list

列出保存的构建凭据（密码用mask遮挡）。 显示当前保存的凭据（包括全局和本地凭据）。 示例: npx @capgo/cli build credentials list # 列出所有应用 npx @capgo/cli build credentials list —appId com.example.app # 列出特定应用

选项：

参数	类型	描述
—appId	string	应用 ID 列表（可选，若省略则列出所有）
—local	boolean	仅从本地 .capgo-credentials.json 中列出凭据

🔹 清除

npx @capgo/cli@latest build credentials clear

清除保存的构建凭据。 从存储中删除凭据。 使用 —appId 和 —platform 来目标特定的凭据。 示例: npx @capgo/cli build credentials clear # 全局清除所有应用 npx @capgo/cli build credentials clear —local # 清除本地凭据 npx @capgo/cli build credentials clear —appId com.example.app —platform ios

选项：

参数	类型	描述
——appId	string	应用 ID（可选，若省略则清除所有应用)
——platform	string	清除平台：ios 或 android（可选，若省略则清除所有平台)
——local	boolean	清除本地 .capgo-credentials.json 代替全局

🔹 更新

npx @capgo/cli@latest build credentials update

更新特定凭据而无需提供所有凭据。 更新现有凭据仅提供您要修改的字段。 平台将自动检测您提供的选项。 示例: npx @capgo/cli build credentials update —ios-provisioning-profile ./new-profile.mobileprovision npx @capgo/cli build credentials update —local —keystore ./new-keystore.jks

选项：

参数	类型	描述
—appId	string	应用 ID（如果省略，会自动从 capacitor.config 中检测）
—platform	string	平台：ios 或 android（根据选项自动检测）
—local	boolean	更新本地 .capgo-credentials.json 代替全局
—certificate	string	P12 证书文件路径
—ios-provisioning-profile	string	配置文件路径或bundleId=path (可重复, 默认为累加)
—overwrite-ios-provisioning-map	boolean	替换整个配置映射而不是合并 (默认: 合并)
—p12-password	string	P12证书密码
—apple-key	string	App Store Connect API密钥 (.p8 文件)路径
—apple-key-id	string	App Store Connect API密钥 ID
—apple-issuer-id	string	App Store Connect 发行者 ID
—apple-team-id	string	App Store Connect Team ID
—apple-id	string	iOS: App Store Connect Team ID邮箱（替代App Store Connect API密钥）
—apple-app-specific-password	string	iOS: TestFlight上传的App特定密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	string	iOS: App Store Connect App ID（数字）
—ios-distribution	string	iOS: 分发模式
—keystore	string	Keystore文件路径 (.keystore或.jks)
—keystore-alias	string	密钥库密钥别名
—密钥库密钥密码	string	密钥库密钥密码
—密钥库存储密码	string	密钥库存储密码
—Play配置	string	Google Play 服务账户 JSON 文件路径
—Android风味	string	Android: 构建的产品风味 (例如生产). 如果您的项目有多个风味，则必填.
—内购更新优先级	string	Android: Google Play 内购更新优先级 (整数 0–5; 更高 = 更紧急).
—输出上传	boolean	将 IPA/APK/AAB 构建输出上传到 Capgo 存储并打印下载链接
—不上传构建输出 (IPA/APK/AAB)	boolean	—不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
—输出链接有效期：1h至7天。示例：1h，6h，2d	string	—跳过构建号码自增
—不跳过构建号码自增	boolean	Skip automatic build number/version code incrementing on future builds
—不跳过市场版本号自增	boolean	—不上传构建输出 (IPA/APK/AAB) 到 __CAPGO_KEEP_0__ 存储
跳过自动构建号码/版本 __CAPGO_KEEP_0__ 自增	boolean	重新启用自动构建号码自增（默认行为）
跳过自动市场版本号自增（当应用已发布时）	boolean	重新启用自动的市场版本号更新 (默认行为)

🔹 管理

npx @capgo/cli@latest build credentials manage

交互式管理保存的构建凭据。 浏览存储的凭据，查看配置的内容，导出一个CI/CD准备好的.env文件， 或删除一个平台的凭据。重用同样的TUI作为 capgo init。 示例: npx @capgo/cli build credentials manage npx @capgo/cli build credentials manage —appId com.example.app npx @capgo/cli build credentials manage —appId com.example.app —platform ios npx @capgo/cli build credentials manage —local

选项：

参数	类型	描述
appId	string	应用 ID（可选，若省略则会提示选择)
平台	string	平台（可选，若省略则会提示选择，ios 或 android)
仅浏览本地 .__CAPGO_KEEP_0__-credentials.json	boolean	Only browse local .capgo-credentials.json

🔹 终端窗口

npx @capgo/cli@latest build credentials migrate

Migrate legacy provisioning profile to the new multi-target format. Converts BUILD_PROVISION_PROFILE_BASE64 to CAPGO_IOS_PROVISIONING_MAP. Discovers the main bundle ID from your Xcode project automatically. npx @capgo/cli build credentials migrate —platform ios

migrate

Example:

选项：

参数	类型	描述
—appId	string	应用 ID（如果省略，会自动从 capacitor.config 检测）
—platform	string	平台（仅支持 ios）
—local	boolean	从本地 .capgo-credentials.json 迁移而不是全局