🔹 构建

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示

🏗️ 通过 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`	自主托管或Capgo开发时的自定义 Supabase 主机 URL
—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`	关闭此次构建的分析和终端回放

🔹 请求

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 电子邮件（替代 API 密钥)
—apple-app-specific-password	`string`	iOS：用于 TestFlight 上传的 App-specific 密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	`string`	iOS：iOS App Store Connect 数字应用 ID（需要与 —apple-id 和 —apple-app-specific-password 一起使用）
—苹果密钥ID	`string`	iOS: App Store Connect API 应用密钥 ID
—apple-issuer-id	`string`	iOS: App Store Connect 发行者 ID
—苹果密钥内容	`string`	iOS: Base64-encoded App Store Connect API key (.p8)
—App Store Connect Team ID	`string`	iOS: App Store Connect Team 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`	张中气网络导航缀名
—张中气网络导航缀名缀。一个事不重转	`string`	—张中气网络导航缀名缀。一个事不重转
—张中气网络导航缀名缀。一个事不重转	`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上传（清除保存的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在创建或重用可编辑版本时使用它。
—商店发布说明	`string`	默认商店发布说明。 Android使用此说明作为Play日志； iOS使用它作为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 > 环境变量 > 保存的凭据
——no-output-upload	`boolean`	覆盖此次构建的输出上传行为 (禁用)。优先级: CLI > 环境变量 > 保存的凭据
——output-retention	`string`	覆盖此次构建的输出链接 TTL (1h 到 7d)。示例: 1h, 6h, 2d。优先级: CLI > 环境变量 > 保存的凭据
——output-record	`string`	成功构建后，写入一个 JSON 记录（jobId，状态，输出 URL，二维码 ASCII，二维码 PNG 路径，完成时间）到一个路径。一个 PNG 二维码 code 也会写入到该路径旁边带有后缀。 `.qr.png` 读取字段回去使用 `build last-output`.
跳过构建缓存恢复	`boolean`	并且不保存此次构建的新缓存条目。构建缓存默认为每个应用程序启用。分区构建缓存
例如	`string`	跳过一个共享的默认缓存，一个应用程序。 `prod`, `staging`跳过构建号码的自增
覆盖保存的凭证以重新启用此次构建的自动构建号码自增。	`boolean`	跳过市场版本号自增
and	`boolean`	跳过自动的营销版本 (CFBundleShortVersionString / versionName) 增加时，应用已经发布。
—sync-ios-version	`boolean`	iOS：在上传项目之前，从 package.json 中同步 Xcode MARKETING_VERSION。
—ai-analytics	`boolean`	在构建失败时，发送日志到 Capgo AI 进行诊断。在交互式终端中，这会跳过确认；在 CI 中，这会自动上传并将分析打印到 stderr。
—no-prescan	`boolean`	跳过自动的预构建扫描
—prescan-ignore-fatal	`boolean`	运行预构建扫描，但永远不会阻塞构建（只报告）
—prescan-skip	`string`	跳过特定的预构建检查（按 id 重复或用逗号分隔）。其他检查仍然运行。
—prescan-warn	`string`	降级特定预扫描检查（可重复或用逗号分隔）。检查仍然运行。
—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`	详细日志输出

构建缓存: Capgo 恢复并保存编译的本机艺术品 (CocoaPods、Gradle 和相关输出) 默认情况下按应用程序进行。使用 --cache-key 来保留 RC 和生产缓存分离;使用 --no-cache 进行一次性清洁构建。API 集成可以传递 cache_key 或 cache_enabled: false 在构建请求负载中。请参见构建缓存和错误排查：缓存恢复错误.

🔹 同步-iOS版本

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

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

示例：

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

选项：

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

🔹 预扫描

npx @capgo/cli@latest build prescan

;此命令独立运行（例如，在CI中）。参见 build request预扫描检查查看完整的检查清单和如何 __CAPGO_KEEP_0__ --skip / --warn 个体规则。

选项:

参数	类型	描述
—平台	`string`	目标平台：ios 或 android（必填）
—路径	`string`	项目目录的路径（默认：当前目录）
-a	`string`	API
—android-分支	`string`	Android: 将要使用的产品风味
—ios-dist	`string`	iOS: 验证的分发模式
—json	`boolean`	输出可读的 JSON 报告
—fail-on-warnings	`boolean`	在 CI 环境下发现警告时退出非零
—ignore-fatal	`boolean`	诊断模式：报告所有内容但总是退出 0
—skip	`string`	跳过特定检查（可重复或用逗号分隔）
—warn	`string`	降级特定检查（可重复或用逗号分隔）到警告
—verbose	`boolean`	—verbose
详细日志输出	`string`	Custom Supabase host URL (for self-hosting or Capgo development)
自主托管或开发环境的自定义 Supabase 主机 URL	`string`	—supa-anon

🔹 自主托管的自定义 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`	JSON 记录的路径，由 —output-record 写入（必填）
—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 帮助程序 (仅限 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路径

🔹 保存

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/ Android: https://capgo.app/docs/cli/cloud-build/android/ 使用 npx @capgo/cli 构建凭据保存 —平台 ios
—证书 ./cert.p12 —p12 密码 “password”
—ios 配置文件 ./profile.mobileprovision
—apple-key ./AuthKey.p8 —apple-key-id “KEY123”
—apple-issuer-id “issuer-uuid” —apple-team-id “team-id” 多目标示例（app + widget 扩展）：使用 npx @capgo/cli 构建凭据保存 —平台 ios
—ios 配置文件 ./App.mobileprovision
—ios 配置文件 com.example.widget=./Widget.mobileprovision
... 使用 npx @capgo/cli 构建凭据保存 —平台 android
—keystore ./release.keystore —keystore-alias “my-key”
—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
——苹果团队ID	`string`	iOS: App Store Connect 团队 ID
——iOS分发	`string`	iOS: 分发模式
——苹果ID	`string`	iOS: Apple ID 电邮（用于 App Store Connect 密码上传，替代 API 密钥）
——苹果应用特定密码	`string`	iOS: 应用特定密码（xxxx-xxxx-xxxx-xxxx）用于 TestFlight 上传
——苹果应用ID	`string`	iOS: 数字 App Store Connect 应用 ID（需要与 —apple-id 和 —apple-app-specific-password 一起使用）
—密钥库	`string`	Android: 密钥库文件路径 (.keystore 或 .jks)
—密钥库别名	`string`	Android: 密钥库密钥别名
—密钥库密钥密码	`string`	Android: 密钥库密钥密码
—密钥库存储密码	`string`	Android: 密钥库存储密码
—Play 配置	`string`	Android: Play 商店服务账户 JSON 文件路径
—Android 风味	`string`	Android: 构建的产品风味 (例如生产). 如果项目有多个风味，则必填
——__CAPGO_KEEP_0__内置更新优先级	`string`	Android: Google Play 内置更新优先级 (整数 0–5; 更高 = 更紧急)
——本地	`boolean`	将凭据保存到项目根目录的 .capgo-凭据.json 文件而不是全局 ~/.capgo-凭据/
——输出上传	`boolean`	上传构建输出 (IPA/APK/AAB) 到 Capgo 存储并打印下载链接
——不上传输出	`boolean`	不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
——输出保留	`string`	输出链接有效期：1小时至7天（默认：1小时）。示例：1小时，6小时，2天
——跳过构建号码增量	`boolean`	跳过自动构建号码/版本 code 增量
———无跳过构建号增加	`boolean`	重新启用自动构建号递增（默认行为）
———跳过营销版本号增加	`boolean`	跳过未来的构建时，已发布的应用程序自动增加营销版本号
———无跳过营销版本号增加	`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

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

选项：

参数	类型	描述
—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中自动检测）
平台	`string`	平台：ios或android（根据选项自动检测）
本地	`boolean`	更新本地 .capgo-credentials.json 代替全局
证书	`string`	P12证书文件路径
ios 配置文件路径	`string`	ios 配置文件路径或 bundleId=path (可重复, 默认为添加)
覆盖整个配置映射代替合并 (默认: 合并)	`boolean`	P12证书密码
苹果密钥	`string`	App Store Connect __CAPGO_KEEP_0__ 密钥 (.p8 文件)路径
苹果密钥 ID	`string`	API
__CAPGO_KEEP_0__	`string`	App Store Connect API Key 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 API key 的替代方案（用于 App Store Connect 证书 ID 的电子邮件）
—apple-app-specific-password	`string`	iOS: TestFlight 上传所需的 App Store Connect app-specific 密码（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`	keystore 密钥别名
—keystore-key-password	`string`	keystore 密钥密码
—keystore-store-password	`string`	keystore 存储密码
—play-config	`string`	Google Play 服务账户 JSON 文件路径
—android-flavor	`string`	Android: 项目中需要构建的产品风格 (例如生产环境). 如果项目有多个风格,则必填.
—in-app-update-priority	`string`	Android: Google Play 内购更新优先级 (整数 0–5; 数值越大,优先级越高).
—output-upload	`boolean`	上传构建输出 (IPA/APK/AAB) 到 Capgo 存储并打印下载链接
—no-output-upload	`boolean`	不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
—output-retention	`string`	输出链接有效期: 1 小时至 7 天。示例: 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 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（可选，若省略则会提示选择)
—platform	`string`	要管理的平台：ios 或 android（可选，若省略则会提示选择)
—local	`boolean`	仅浏览本地 .capgo-credentials.json

🔹 迁移

npx @capgo/cli@latest build credentials migrate

将遗留的配置文件迁移到新的多目标格式。将 BUILD_PROVISION_PROFILE_BASE64 转换为 CAPGO_IOS_PROVISIONING_MAP。自动从 Xcode 项目中发现主包 ID。 npx @capgo/cli build credentials migrate —platform ios

示例:

Example:

选项:

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