🔹 构建

复制一个设置提示，包括安装步骤和此插件的完整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`	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 电邮（替代 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
—苹果发行者 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方案	`string`	iOS：Xcode 构建方案（默认：App）
—ios-target	`string`	iOS: Xcode目标（默认：与方案相同）
——ios-distribution	`string`	iOS: 分发模式
——ios-provisioning-profile	`string`	iOS: 配置文件路径或bundleId=path映射（可重复）
——android-keystore-file	`string`	Android: 基础64编码的keystore文件
——keystore-key-alias	`string`	Android: keystore密钥别名
——keystore-key-password	`string`	Android: keystore密钥密码
——keystore-store-password	`string`	Android: Keystore 密钥库存储密码
—play-config-json	`string`	Android: Google Play 服务账号 JSON（Base64编码）
—android-flavor	`string`	Android: 构建的产品风味（例如生产环境）。如果项目有多个风味，则必填。
—android-track	`string`	Android: 上传到 Google Play 的跟踪（内部、alpha、beta、生产）。如果没有 —submit-to-store-review，则默认为内部。如果有 —submit-to-store-review 但没有设置跟踪，则默认为生产。优先级：CLI > 环境变量 > 保存的凭据
—android-release-status	`string`	Android: Google Play 发布状态（草稿、已完成、进行中、已暂停）。如果没有 —submit-to-store-review，则默认为草稿。如果有 —submit-to-store-review 但没有设置状态，则默认为已完成。优先级：CLI > 环境变量 > 保存的凭据
—in-app-update-priority	`string`	Android: Google Play 内部更新优先级（整数 0–5；越高越紧急）。请参见 https://developer.android.com/guide/playcore/in-app-updates. 优先级：CLI > env > 保存的凭据
——不上传到Play商店	`boolean`	跳过此构建的Play Store上传（清除保存的Play配置）。需要—output-upload。
——提交到商店审核	`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使用它作为App Store“What’s New”文本的fallback。
——商店发布说明（本地化）	`string`	本地化商店发布说明（可重复），例如—store-release-notes-locale en-US=“Bug fixes” —store-release-notes-locale 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，二维码 ASCII，二维码 PNG 路径，完成时间）到一个路径。一个 PNG 二维码 code 也会写入到该路径旁边带有后缀。 `.qr.png` 读取以下字段： `build last-output`.
—无跳过构建号增量	`boolean`	覆盖保存的凭证以重新启用此构建的自动构建号增量。
—跳过市场版本增量	`boolean`	在应用已发布时跳过自动市场版本（CFBundleShortVersionString / versionName）增量。
—同步 iOS 版本	`boolean`	iOS：在上传项目之前从 package.json 同步 Xcode MARKETING_VERSION。
—AI 分析	`boolean`	在构建失败时，将日志发送到 Capgo AI 进行诊断。在交互式终端中，这会跳过确认；在 CI 中，这会自动上传并将分析打印到 stderr。
—无预扫描	`boolean`	跳过自动预构建扫描
——忽略扫描错误	`boolean`	运行预构建扫描，但永远不会阻止构建（仅报告）
——忽略扫描	`string`	跳过特定扫描检查（通过 id 重复或逗号分隔）。其他检查仍然运行。
——警告扫描	`string`	将特定扫描检查（通过 id 重复或逗号分隔）降级为警告。检查仍然运行。
——构建失败时警告	`boolean`	将扫描警告视为致命错误
——自动发送构建日志到__CAPGO_KEEP_0__支持（无需电子邮件）。__CAPGO_KEEP_1__支持将收到电子邮件通知并会通过电子邮件跟进。与——ai-analytics相加。	`boolean`	On a CI/CD build failure, automatically upload the build logs to Capgo support (no email required). Capgo support is notified and will follow up by email. Additive to —ai-analytics.
——send-logs-to-support的过时别名	`boolean`	——send-logs-to-support的过时别名
-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 同步、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)
__CAPGO_KEEP_0__	`boolean`	诊断模式：报告所有内容但总是退出 0
__CAPGO_KEEP_0__	`string`	跳过特定检查（可重复或用逗号分隔）
__CAPGO_KEEP_0__	`string`	将特定检查（可重复或用逗号分隔）降级为警告
__CAPGO_KEEP_0__	`boolean`	启用详细日志输出的冗长输出
__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，验证它并将其保存到 ~/.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
—证书 ./cert.p12 —p12密码 “password”
—ios 配置文件 ./profile.mobileprovision
—apple-key ./AuthKey.p8 —apple-key-id “KEY123”
—apple-发行者 ID “issuer-uuid” —apple-团队 ID “team-id” 多目标示例（app + 小部件扩展）： npx @capgo/cli build credentials save —platform ios
—ios 配置文件 ./App.mobileprovision
—ios 配置文件 com.example.widget=./Widget.mobileprovision
… npx @capgo/cli build credentials save —platform android
—keystore ./release.keystore —keystore-别名 “my-key”
—keystore-密钥密码 “key-pass”
—play-config ./service-account.json 本地存储（按项目）： npx @capgo/cli build credentials save —local —platform ios …

示例：

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 密钥别名
——keystore-key-password	`string`	Android: Keystore key 密码
——keystore-store-password	`string`	Android: Keystore store 密码
——play-config	`string`	Android: Play Store 服务账户 JSON 路径
——android-flavor	`string`	Android: 产品风味（例如生产）
——in-app-update-priority	`string`	Android: Google Play 内购更新优先级（整数 0–5；更高 = 更紧急）
——local	`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`	跳过自动营销版本增加（当应用已发布时）
———无跳过市场版本更新	`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 # 列出特定应用

选项：

参数	类型	描述
应用ID	`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`	配置文件路径或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 API ID邮箱（可替代App Store Connect Team ID）
—apple-app-specific-password	`string`	iOS: TestFlight上传所需的App特定密码（xxxx-xxxx-xxxx-xxxx）
—apple-app-id	`string`	iOS: App Store Connect app id（需与—apple-id和—apple-app-specific-password一起使用）
—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`	将 Capgo 存储中的构建输出 (IPA/APK/AAB) 上传并打印下载链接
无输出上传	`boolean`	不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
输出链接有效期：1小时至7天。示例：1小时，6小时，2天	`string`	跳过自动构建号码/版本 __CAPGO_KEEP_0__ 自动递增
无跳过自动构建号码递增	`boolean`	Skip automatic build number/version code incrementing on future builds
跳过自动市场版本号递增（当应用已发布时）	`boolean`	无跳过自动市场版本号递增
跳过自动市场版本号递增（当应用已发布时）	`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`	平台（可选，若省略则会提示选择)
仅浏览本地 .__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

__CAPGO_KEEP_0__

Example:

选项:

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