🔹 构建

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

🏗️ 通过 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

Pass --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

🔹 Needed

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或公共默认频道进行比较的频道。默认为CapacitorUpdater.defaultChannel或公共默认频道
—package-json	`string`	多包仓库的package.json文件路径（逗号分隔）
—node-modules	`string`	多包仓库的node_modules目录路径（逗号分隔）
—verbose	`boolean`	详细日志输出
—supa-host	`string`	自主托管或Capgo开发时的自定义Supabase主机URL
—supa-anon	`string`	自主托管时的自定义Supabase匿名密钥

🚀 Init

Alias: onboarding

npx @capgo/cli@latest build init

交互式设置构建凭据 (iOS: 自动配置证书 + 配置文件; Android: 自动配置 keystore + Google OAuth 并配置 GCP 服务账号和 Play Console 邀请)

选项:

参数	类型	描述
-a	`string`	API 键用于链接到您的账号
-p	`string`	要上线的平台 (ios 或 android)。如果省略，会自动检测当只有一个本地文件夹存在时；否则会提示。
--supa-host	`string`	自定义 Supabase 主机 URL（用于自主托管或 Capgo 开发）
—无分析	`boolean`	禁用此次运行的构建引导分析和终端回放

🔹 请求

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`	构建模式：调试或发布（默认：发布）
__build-certificate-base64	`string`	iOS：Base64编码的.p12证书
__p12-password	`string`	iOS：证书密码（如果证书没有密码，则可选）
__apple-id	`string`	iOS：用于上传应用特定密码的Apple ID电子邮件（App Store ConnectAPI密钥的替代方案）
__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一起使用）
__apple-key-id	`string`	iOS: App Store Connect API 应用密钥ID
—苹果发行者 ID	`string`	iOS: App Store Connect 发行者 ID
—苹果密钥内容	`string`	iOS: Base64编码的App Store ConnectAPI密钥(.p8)
—App Store Connect Team ID	`string`	iOS: App Store Connect 团队 ID
—iOS方案	`string`	iOS: 使用 Xcode 构建方案（默认：App）
—ios-target	`string`	iOS: 在 Xcode 中，目标设置为读取构建设置（默认值：与方案相同）
—iOS分发	`string`	iOS: 分发模式
—ios-provisioning-profile	`string`	iOS: Provisioning profile路径或bundleId=path映射（可重复）
—android-keystore-file	`string`	Android: Base64编码的keystore文件
—keystore-key-alias	`string`	Android: Keystore密钥别名
—keystore-key-password	`string`	Android: Keystore密钥密码
—keystore-store-password	`string`	Android: Keystore存储密码
—play-config-json	`string`	Android: Base64-encoded Google Play service account JSON
—android-flavor	`string`	Android: 项目中需要构建的产品风格（例如生产环境）。如果项目有多个风格，则必填。
—in-app-update-priority	`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`	上传后将此版本提交到App Store审查，而不是将其留作草稿/未激活的构建。Android标记Play发布完成；iOS将处理后的TestFlight构建提交到App Store审查。
—store-release-name	`string`	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	`string`	__CAPGO_KEEP_1__
__CAPGO_KEEP_2__	`string`	__CAPGO_KEEP_3__
__CAPGO_KEEP_4__	`string`	__CAPGO_KEEP_5__
__CAPGO_KEEP_6__	`boolean`	__CAPGO_KEEP_7__
__CAPGO_KEEP_8__	`boolean`	__CAPGO_KEEP_9__
__CAPGO_KEEP_10__	`boolean`	Override 本次构建的输出上传行为 (启用). 优先级: CLI > env > saved credentials
—no-output-upload	`boolean`	Override 本次构建的输出上传行为 (禁用). 优先级: CLI > env > saved credentials
—output-retention	`string`	Override 本次构建的输出链接有效期 (1h 到 7d). 示例: 1h, 6h, 2d. 优先级: CLI > env > saved credentials
—output-record	`string`	成功构建后，写入一个 JSON 记录 (jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) 到一个路径。一个 PNG QR code 也会写入到该路径的旁边，带有 `.qr.png` suffix. 读取字段回 `build last-output`.
—no-skip-build-number-bump	`boolean`	Override 保存的凭据以重新启用自动构建号递增功能本次构建
—skip-marketing-version-bump	`boolean`	跳过自动市场版本 (CFBundleShortVersionString / versionName) 增加，当应用已经发布时
—iOS同步版本	`boolean`	iOS：在上传项目之前从package.json同步Xcode MARKETING_VERSION。
—AI分析	`boolean`	在构建失败时，发送日志到Capgo AI进行诊断。在交互式终端中跳过确认；在CI中自动上传并将分析打印到stderr。
—跳过预扫描	`boolean`	跳过自动预构建扫描
—预扫描忽略致命错误	`boolean`	在预构建扫描时不阻塞构建（只报告）
—警告为致命错误	`boolean`	将预扫描警告视为致命错误
—自动发送日志至支持	`boolean`	在CI/CD构建失败时，自动上传构建日志至Capgo支持（无需发送电子邮件）。Capgo支持将收到电子邮件并会通过电子邮件跟进。与—AI分析相加。
—发送日志	`boolean`	已弃用 —send-logs-to-support 的别名
-a	`string`	API 用于链接到您的帐户的密钥
—自定义 Supabase 主机 URL（用于自主托管或 __CAPGO_KEEP_0__ 开发）	`string`	Custom Supabase host URL (for self-hosting or Capgo development)
—详细输出和日志	`string`	iOS 版本同步
iOS 版本同步	`boolean`	自定义 Supabase 主机 URL（用于自主托管或 __CAPGO_KEEP_0__ 开发）

🔹 自定义 Supabase 匿名密钥（用于自主托管）

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`	项目目录的路径（默认：当前目录）
—检查	`boolean`	仅检查; MARKETING_VERSION 不一致时退出非零

🔹 预扫描

npx @capgo/cli@latest build prescan

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

选项：

参数	类型	描述
—平台	`string`	目标平台：ios 或 android（必填）
—路径	`string`	项目目录路径（默认：当前目录）
-a	`string`	API用于链接到您的帐户
—android-风味	`string`	Android：构建将使用的产品风味
—ios-分发	`string`	iOS：用于验证的分发模式
—json	`boolean`	输出机器可读的JSON报告
—警告时退出	`boolean`	在 CI 中当发现警告时退出 (非零)
—忽略致命	`boolean`	诊断模式：报告所有内容但总是退出 0
—详细	`boolean`	启用详细输出和详细日志
—超级主机	`string`	自定义 Supabase 主机 URL（用于自主托管或 Capgo 开发）
—超级匿名	`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`	写入 —output-record 后的 JSON 记录路径（必填）
—field	`string`	打印单个字段（可选：jobId、appId、platform、buildMode、status、outputUrl、qrCodeAscii、qrCodePngPath、finishedAt、schemaVersion）
—二维码	`boolean`	Print the rendered ASCII QR code (shortcut for —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

Create an App Store Connect team API key with a guided macOS helper (macOS only). Opens a native window that walks you through Apple’s App Store Connect UI in an embedded browser, auto-captures the Issuer ID + Key ID, intercepts the one-time .p8, validates it against Apple, and saves it to ~/.appstoreconnect/private_keys. Progress statistics are forwarded to Capgo analytics (disable with CAPGO_DISABLE_TELEMETRY). npx @capgo/cli build credentials apple-key —appId com.example.app

打开一个本机窗口，带您通过 Apple 的 App Store Connect UI 在嵌入式浏览器中进行引导式操作，自动捕获 Issuer ID + Key ID，拦截一次性 .p8，验证它与 Apple 并将其保存到 ~/.appstoreconnect/private_keys 中。进度统计信息将传递到 __CAPGO_KEEP_1__ 分析 (通过 __CAPGO_KEEP_2___DISABLE_TELEMETRY 禁用)。npx @__CAPGO_KEEP_3__/__CAPGO_KEEP_4__ 构建凭据 apple-key —appId com.example.app

Example:

复制到剪贴板

选项：	参数：	描述
-a	`string`	API key to link to your account
—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-凭据/凭据.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-issuer-id “issuer-uuid” —apple-team-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-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：证书密码 (如果证书没有密码，则可选)
—apple-key	`string`	iOS: App Store Connect API 证书路径
—apple-key-id	`string`	iOS: App Store Connect API Key ID
—apple-issuer-id	`string`	iOS: App Store Connect Issuer ID
—apple-team-id	`string`	iOS: App Store Connect Team ID
—ios-distribution	`string`	iOS: 分发模式
—apple-id	`string`	iOS: App Store Connect API Key 的 Apple ID邮箱（App Store Connect 证书替代）
—apple-app-specific-password	`string`	iOS: App-specific password (xxxx-xxxx-xxxx-xxxx) for TestFlight uploads
—apple-app-id	`string`	iOS: 笔给 App Store Connect app id (上为 —apple-id 和 —apple-app-specific-password)
—keystore	`string`	中国: 路dbf为为存适器的路dbf器主 (.keystore 或 .jks)
—keystore-alias	`string`	中国: 路d为存适器的路dbf器为名
—keystore-key-password	`string`	中国: 路d为存适器的路dbf器密当输入密
—keystore-store-password	`string`	中国: 路d为存适器的路dbf器床存密当输入密
—play-config	`string`	Android: 到 Google Play 商店服务账户 JSON 文件的路径
—android-flavor	`string`	Android: 产品风味来构建 (例如生产). 如果您的项目有多个风味，则必填
—in-app-update-priority	`string`	Android: Google Play 内购更新优先级 (整数 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天
—跳过构建号码升级	`boolean`	跳过自动构建号码/版本 code 增加于未来构建
—不跳过构建号码升级	`boolean`	恢复自动构建号码增量（默认行为）
—跳过市场版本号码升级	`boolean`	跳过自动市场版本号码升级于未来构建时，应用已发布
—不跳过市场版本号码升级	`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

清除保存的构建凭据。从存储中删除凭据。使用 —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 自动检测）
—平台	`string`	平台：ios 或 android（自动检测选项）
—本地	`boolean`	更新本地 .capgo-credentials.json 代替全局
—证书	`string`	P12 证书文件路径
—ios 配置文件	`string`	配置文件路径或 bundleId=path（可重复，按需添加）
—覆盖 ios 配置文件映射	`boolean`	覆盖整个配置文件映射代替合并（默认：合并）
—p12 密码	`string`	P12 证书密码
—apple-key	`string`	App Store Connect API key (.p8 文件)
—apple-key-id	`string`	App Store Connect API Key ID
—apple-issuer-id	`string`	App Store Connect Issuer ID
—apple-team-id	`string`	App Store Connect Team ID
—apple-id	`string`	iOS: App Store Connect API key 的 Apple ID 邮箱（用于替代 App Store Connect API key）
—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 (数字)
—ios-distribution	`string`	iOS: 分发模式
—keystore	`string`	.keystore 或 .jks 文件的密钥库路径
—keystore-alias	`string`	密钥库密钥别名
—keystore-key-password	`string`	密钥库密钥密码
—keystore-store-password	`string`	密钥库存储密码
—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天
—跳过构建号增加	`boolean`	跳过自动构建号/版本 code 增加
—不跳过构建号增加	`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

参数

类型	描述	—appId
要管理的应用 ID（可选，若省略则会提示选择）	`string`	—platform
要管理的平台：ios 或 android（可选，若省略则会提示选择）	`string`	—local
仅浏览本地 .__CAPGO_KEEP_0__-credentials.json	`boolean`	Only browse local .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平台
—local	`boolean`	从本地.capgo-credentials.json迁移而不是全局