🔹 构建

🏗️ 通过 Capgo Cloud 管理原生 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 key to link to your account
-c	string	与CapacitorUpdater.defaultChannel或公共默认频道进行比较的频道
—package-json	string	多包仓库的package.json文件路径（逗号分隔）
—node-modules	string	多包仓库的node_modules目录路径（逗号分隔）
—verbose	boolean	启用详细日志的verbose输出
—supa-host	string	自主托管或开发环境下的自定义Supabase主机URL（Capgo）
—supa-anon	string	自主托管下的自定义Supabase匿名密钥

🚀 Init

别名： onboarding

npx @capgo/cli@latest build init

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

选项：

参数	类型	描述
-a	string	API key to link to your account
-p	string	平台 (ios 或 android) 用于 onboard。如果省略，会自动检测当只有一个本机文件夹存在时；否则会提示。
—supa-host	string	自定义 Supabase 主机 URL（用于自主托管或 Capgo 开发）
—no-analytics	boolean	禁用此次运行的构建 onboard 分析和终端重放

🔹 请求

npx @capgo/cli@latest build request

从 Capgo 云请求一个原生构建。 此命令将压缩您的项目目录并将其上传到 Capgo 进行构建。 构建将被处理并直接发送到应用商店。 凭据永远不会在 Capgo 服务器上存储;它们在构建后删除。保存它们之前请求构建：

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: 证书密码 (如果证书没有密码则可选)
__CAPGO_KEEP_0__	string	iOS: 应用专用密码上传（App Store Connect API key 的替代方案）
__CAPGO_KEEP_0__	string	iOS: TestFlight 上传的应用专用密码（xxxx-xxxx-xxxx-xxxx）
__CAPGO_KEEP_0__	string	iOS: App Store Connect 应用 ID（数字，需要与 —apple-id 和 —apple-app-specific-password 一起使用）
__CAPGO_KEEP_0__	string	iOS: App Store Connect API Key ID
__CAPGO_KEEP_0__	string	iOS: App Store Connect 发行者 ID
__CAPGO_KEEP_0__	string	iOS: Base64-encoded App Store Connect API key (.p8)
—苹果商店连接团队ID	string	iOS: 苹果商店连接团队ID
—iOS构建方案	string	iOS: Xcode 构建方案（默认：App）
—iOS读取构建设置的Xcode目标（默认：同构建方案）	string	—iOS发布模式
iOS: 发行模式	string	—iOS签名配置文件
iOS: 签名配置文件路径或bundleId=path映射（可重复）	string	—安卓keystore文件
—安卓keystore文件	string	安卓：使用Base64编码的keystore文件
—keystore-key-alias	string	安卓: 密钥库密钥别名
—密钥库密钥密码	string	安卓: 密钥库密钥密码
密钥库存储密码	string	安卓: 密钥库存储密码
—play-config-json	string	安卓: 基于Base64的Google Play服务账户JSON
—安卓版本	string	Android: 产品风味用于构建（例如生产环境）。如果您的项目有多个风味，则必填。
应用内更新优先级	string	Android: Google Play 内购更新优先级（整数 0–5；更高 = 更紧急）。请参阅 https://developer.android.com/guide/playcore/in-app-updates. 优先级：CLI > env > 保存的凭据
—no-playstore-upload	boolean	跳过此构建的Play Store上传（清除保存的Play配置）。需要 —output-upload。
—submit-to-store-review	boolean	上传后，将该应用程序的商店发布提交审查，而不是将其留作草稿/未激活的构建。Android标记Play发布完成；iOS将处理后的TestFlight构建提交到App Store审查。
—store-release-name	string	商店发布名称/版本标签。Android将其发送为Google Play的version_name；iOS在创建或重用可编辑版本时使用它作为App Store的版本。
—store-release-notes	string	默认商店发布说明。Android使用此作为Play的更改日志；iOS使用它作为App Store的fallback What’s New文本。
—store-release-notes-locale	string	本地化商店发行说明（可重复），例如 —store-release-notes-locale en-US=“Bug fixes” —store-release-notes-locale fr-FR=“Corrections”。
—ios-testflight-groups	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	Override 本次构建的输出链接 TTL（1小时到7天）。示例：1小时，6小时，2天。优先级：CLI > env > 保存的凭据
—output-record	string	在构建成功后，写入一个 JSON 记录（jobId，状态，输出 URL，QR 码 ASCII，QR 码 PNG 路径，完成时间）到一个路径。一个 PNG QR code 也会写入到该路径旁边，带有后缀。读取字段回 code .qr.png —no-skip-build-number-bump build last-output.
覆盖保存的凭据，以便重新启用本次构建的自动构建号递增功能。	boolean	—skip-marketing-version-bump
在应用程序已经发布时，跳过自动的市场版本（CFBundleShortVersionString / versionName）递增。	boolean	—sync-ios-version
iOS：在上传项目之前，同步 Xcode MARKETING_VERSION 从 package.json。	boolean	—ai-analytics
在构建失败时，发送日志到 __CAPGO_KEEP_0__ AI 进行诊断。在交互式终端中，这会跳过前置确认；在 CI 中，这会自动上传并将分析打印到 stderr。	boolean	On build failure, send logs to Capgo AI for diagnosis. In interactive terminals this skips the upfront confirmation; in CI this auto-uploads and prints the analysis to stderr.
—no-prescan	boolean	跳过自动预构建扫描
—prescan-ignore-fatal	boolean	在预构建扫描时不阻塞构建（仅报告）
—fail-on-warnings	boolean	将预构建扫描警告视为致命错误
—send-logs-to-support	boolean	在CI/CD构建失败时，自动将构建日志上传到Capgo支持（无需电子邮件）。Capgo支持将收到通知并通过电子邮件跟进。—ai-analytics可添加。
—send-logs	boolean	—send-logs-to-support的过时别名
-a	string	API账户链接密钥
—supa-host	string	自定义 Supabase 主机 URL（用于自主托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase 匿名密钥（用于自主托管）
—verbose	boolean	启用详细日志的verbose输出

🔹 Sync-ios-version

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

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

示例：

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中）。

选项：

参数	类型	描述
—平台	string	目标平台：ios或android（必填）
—路径	string	项目目录的路径（默认：当前目录）
-a	string	API key to link to your account
—android-flavor	string	中国：分类类事为导航帮内定一个用
—ios-dist	string	欢迎中国：充给帮内定一个用
—json	boolean	编程为机器给笔计一个给笔计给
—fail-on-warnings	boolean	发起一为不常用的回答。发起一为不常用的回答
—ignore-fatal	boolean	给笔事为给笔事。给笔事一为给笔事一为给笔事
—verbose	boolean	详细日志输出
—supa-host	string	自建或开发环境时的 Supabase 主机 URL（Capgo）
—supa-anon	string	自建 Supabase anon key（__CAPGO_KEEP_0__）

🔹 最后输出

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	输出记录由 —output-record 写入的 JSON 文件路径（必填）
—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 中立即删除
• 构建输出可选上传用于时间限制下载链接 📚 文档： https://capgo.app/docs/cli/cloud-build/ios/ https://__CAPGO_KEEP_0__.app/docs/__CAPGO_KEEP_1__/cloud-build/ios/ https://capgo.app/docs/cli/cloud-build/android/

🔹 https://__CAPGO_KEEP_0__.app/docs/__CAPGO_KEEP_1__/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	以JSON格式打印捕获的Key ID / Issuer ID / .p8路径

🔹 Save

npx @capgo/cli@latest build credentials save

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

• ~/.capgo-credentials/credentials.json (默认，全球)
• .capgo-credentials.json 在项目根目录 (使用 —local 标志) ⚠️ 必须在请求构建之前保存凭据。 🔒 这些凭据永远不会在 Capgo 服务器上永久存储。 它们在构建完成后立即删除。 📚 配置指南: iOS: https://capgo.app/docs/cli/cloud-build/ios/ 安卓： 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
  多目标示例（app + 小部件扩展）：
  npx @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__ build credentials save —platform ios
  … npx @capgo/cli build credentials save —platform android
  —ios-provisioning-profile com.example.widget=./Widget.mobileprovision、…
  —keystore-key-password “key-pass”
  —play-config ./service-account.json 本地存储 (每个项目): npx @capgo/cli build credentials save —local —platform ios …

示例：

iOS Example:

选项：

参数	类型	描述
—appId	string	应用 ID（例如，com.example.app）(必填)
—平台	string	平台: ios 或 android (必填)
—证书	string	iOS: .p12 证书文件路径
—ios-分发配置	string	iOS: 分发配置文件路径或 bundleId=path (可重复)
—p12-密码	string	iOS: 证书密码 (如果证书没有密码则可选)
—苹果密钥	string	iOS: .p8 App Store Connect API 密钥路径
—苹果密钥 ID	string	iOS: App Store Connect API 密钥 ID
—苹果发行者 ID	string	iOS: App Store Connect 发行者 ID
__CAPGO_KEEP_0__	string	iOS: App Store Connect 团队 ID
—ios-distribution	string	iOS: 分发模式
—apple-id	string	iOS: App Store Connect Apple ID 电子邮件（替代 API 密钥）
—apple-app-specific-password	string	iOS: TestFlight 上传所需的 App 专用密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	string	iOS: App Store Connect 应用程序 ID（数字）
—keystore	string	Android: 导入.keystore或.jks文件的路径
__CAPGO_KEEP_0__	string	Android: 导入.keystore或.jks文件的别名
__CAPGO_KEEP_0__	string	Android: 导入.keystore或.jks文件的密码
__CAPGO_KEEP_0__	string	Android: 导入.keystore或.jks文件的存储密码
__CAPGO_KEEP_0__	string	Android: 导入Google Play服务账户JSON文件的路径
__CAPGO_KEEP_0__	string	Android: 构建的产品风味（例如生产环境）
__CAPGO_KEEP_0__	string	Android: Google Play 在-app 更新优先级（整数 0–5；更高 = 更紧急）。忽略以保持 Play 的现有值不变。
—local	boolean	将凭据保存到项目根目录的 .capgo-credentials.json 文件，而不是全局 ~/.capgo-credentials/ 文件夹中。
—output-upload	boolean	将构建输出（IPA/APK/AAB）上传到 Capgo 存储并打印下载链接。
—no-output-upload	boolean	不要将构建输出（IPA/APK/AAB）上传到 Capgo 存储。
—output-retention	string	输出链接有效期：1小时到7天（默认：1小时）。示例：1小时，6小时，2天。
—skip-build-number-bump	boolean	跳过自动构建号/版本 code 自动递增功能
—no-skip-build-number-bump	boolean	重新启用自动构建号递增 (默认行为)
—skip-marketing-version-bump	boolean	在应用已发布时，跳过未来构建的自动营销版本号更新
—no-skip-marketing-version-bump	boolean	重新启用自动营销版本号更新 (默认行为)

📋 列表

npx @capgo/cli@latest build credentials list

列出保存的构建凭证（密码已掩码）。 显示当前保存的凭证（包括全局和本地凭证）。 示例: 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

Clear saved build credentials. Remove credentials from storage. Use —appId and —platform to target specific credentials. Examples: npx @capgo/cli build credentials clear # Clear all apps (global) npx @capgo/cli build credentials clear —local # Clear local credentials npx @capgo/cli build credentials clear —appId com.example.app —platform ios

Terminal window

参数	类型	描述
—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 代替全局
—证书	string	P12证书文件路径
—ios-分发配置	string	分发配置文件路径或bundleId=path (可重复, 默认为追加)
—覆盖ios-分发映射	boolean	覆盖整个分发映射而不是合并 (默认: 合并)
—p12-密码	string	P12证书密码
—苹果密钥	string	App Store Connect API 密钥 (.p8 文件)路径
—苹果密钥ID	string	App Store Connect API 密钥 ID
—apple-issuer-id	string	App Store Connect 发行者 ID
—apple-team-id	string	App Store Connect 团队 ID
—apple-id	string	iOS: App Store Connect 应用程序专用密码上传的电子邮件 (替代 App Store Connect API 密钥)
—apple-app-specific-password	string	iOS: TestFlight 上传的应用程序专用密码 (xxxx-xxxx-xxxx-xxxx)
—apple-app-id	string	iOS: App Store Connect 应用程序 ID (与 —apple-id 和 —apple-app-specific-password 一起使用)
—ios-distribution	string	iOS: 分发模式
—密钥库	string	密钥库文件路径 (.keystore 或 .jks)
—密钥库别名	string	密钥库密钥别名
—密钥库密钥密码	string	密钥库密钥密码
—密钥库存储密码	string	密钥库存储密码
—Google Play 配置	string	Google Play 服务账户 JSON 文件路径
—Android 风味	string	Android: 构建的产品风味 (例如生产). 如果您的项目有多个风味，则必填.
—in-app-update-priority	string	Android: Google Play 在-app 更新优先级 (整数 0–5; 更高 = 更紧急)
—output-upload	boolean	上传构建输出 (IPA/APK/AAB) 到 Capgo 存储并打印下载链接
—no-output-upload	boolean	不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
—output-retention	string	输出链接 TTL: 1h 到 7d。示例：1h，6h，2d
—skip-build-number-bump	boolean	跳过自动构建号/版本 code 自动递增
—no-skip-build-number-bump	boolean	重新启用自动构建号递增（默认行为）
—跳过市场版本更新	boolean	自动市场版本更新在未发布的应用程序中跳过
—不跳过市场版本更新	boolean	重新启用自动市场版本更新（默认行为）

🔹 管理

npx @capgo/cli@latest build credentials manage

交互式管理保存的构建凭据。 浏览存储的凭据，查看已配置的内容，导出一个CI/CD准备好的.env文件， 或删除一个平台的凭据。重用相同的TUI。 示例: npx @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__ build credentials manage npx @__CAPGO_KEEP_2__/__CAPGO_KEEP_3__ build credentials manage —appId com.example.app npx @__CAPGO_KEEP_4__/__CAPGO_KEEP_5__ build credentials manage —appId com.example.app —platform ios npx @__CAPGO_KEEP_6__/__CAPGO_KEEP_7__ build credentials manage —local capgo init. Examples: 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

参数：

Param	类型	描述
—appId	string	用于管理的 App ID（可选，若省略则会提示选择）
—platform	string	要管理的平台：ios 或 android（可选，若省略则会提示选择）
—local	boolean	仅浏览本地 .capgo-credentials.json

🔹 迁移

npx @capgo/cli@latest build credentials migrate

Migrate legacy provisioning profile to the new multi-target format. 将BUILD_PROVISION_PROFILE_BASE64转换为CAPGO_IOS_PROVISIONING_MAP。 自动从您的Xcode项目中发现主bundle ID。 npx @capgo/cli build credentials migrate —platform ios

示例：

Example:

选项：

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