🔹 构建

🏗️ 通过 Capgo 云管理本机 iOS/Android 构建。

构建访问和输出

本机云构建在每个 Capgo 计划上都可用。构建凭证从不存储在 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	详细日志输出
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—supa-anon	string	自定义 Supabase 匿名密钥（用于自主托管）

🚀 Init

Alias: onboarding

npx @capgo/cli@latest build init

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

选项:

参数	类型	描述
-a	string	API
-p	string	平台（ios或android）
--supa-host	string	自定义Supabase主机URL（用于自主托管或Capgo开发）
--no-analytics	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 .

选项：

参数	类型	描述
—路径	string	构建项目的路径（默认：当前目录）
—node-modules	string	多包项目的node_modules目录路径（逗号分隔）
—平台	string	目标平台：ios或android（必填）
—构建模式	string	构建模式：debug或release（默认：release）
—构建证书（base64）	string	ios：base64编码的.p12证书
——p12-密码	string	iOS: 证书密码（如果证书没有密码则可选)
——apple-id	string	iOS: App Store Connect ID（用于替代API密钥）
——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一起使用）
——apple-key-id	string	iOS: App Store Connect API密钥ID
——apple-issuer-id	string	iOS: App Store Connect 发行者ID
—apple-key-content	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 构建目标（读取构建设置， 默认：同构建方案）
—ios-distribution	string	iOS: 发布模式
—ios-provisioning-profile	string	iOS: 供应链配置文件路径或 bundleId=path 映射（可重复）
—安卓密钥存储文件	string	安卓：Base64编码的keystore文件
—keystore-key-alias	string	安卓：密钥库密钥别名
—keystore-key-password	string	安卓：密钥库密钥密码
—keystore存储密码	string	安卓：密钥库存储密码
—play-config-json	string	安卓：Base64编码的Google Play服务账户JSON
—安卓风味	string	安卓：产品风味用于构建（例如生产）。如果您的项目有多个风味，则必填。
——android-track	string	Android: Google Play track for this upload (internal, alpha, beta, production). Default without —submit-to-store-review: internal. With —submit-to-store-review and no track set: production. Precedence: CLI > env > saved credentials
——android-release-status	string	Android: Google Play release status (draft, completed, inProgress, halted). Default without —submit-to-store-review: draft. With —submit-to-store-review and no status set: completed. Precedence: CLI > env > saved credentials
——in-app-update-priority	string	Android: Google Play 内购更新优先级（整数 0–5；越高越紧急）。见 https://developer.android.com/guide/playcore/in-app-updates. 优先级：CLI > 环境变量 > 保存的凭据
——no-playstore-upload	boolean	跳过此次构建的Google Play商店上传（清空已保存的Play配置）。需要 —output-upload。
——submit-to-store-review	boolean	After upload, submit the store release for review instead of leaving it as a draft/inactive build. On Android this defaults to the production track with release_status completed (override with —android-track / PLAY_STORE_TRACK and —android-release-status / PLAY_STORE_RELEASE_STATUS). On iOS this submits the processed TestFlight build to App Store review.
——store-release-name	string	Android应用商店版本名称/版本号标签。Android将其发送为Google Play的version_name; iOS在创建或重用可编辑版本时使用它作为App Store的版本。
——store-release-notes	string	Android应用商店的默认更新日志; iOS使用它作为App Store的“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	仅此次构建覆盖输出链接有效期（1小时至7天）。示例：1小时，6小时，2天。优先级：CLI > env > 保存的凭据
—output-record	string	成功构建后，将一个 JSON 记录（jobId，状态，输出 URL，QR 码 ASCII，QR 码 PNG 路径，完成时间）写入一个路径。一个 PNG QR 码 code 也会在该路径旁边写入，带有后缀。读取字段使用 .qr.png —no-cache build last-output.
跳过构建缓存恢复	boolean	和 （And） 不为此次构建保存新的缓存条目。构建缓存默认为每个应用程序启用。
—缓存键	string	根据环境、 branch 或 Android 风味（例如）将构建缓存分区（例如） prod, stagingOmit 为应用程序共享一个默认缓存。
—不跳过构建号增量	boolean	覆盖保存的凭据以重新启用此构建仅自动构建号增量。
—跳过营销版本增量	boolean	当应用程序已发布时，跳过自动营销版本（CFBundleShortVersionString / versionName）增量。
—同步 iOS 版本	boolean	iOS：在上传项目之前，同步 Xcode MARKETING_VERSION 从 package.json。
— AI 分析	boolean	在构建失败时，发送日志到 Capgo AI 进行诊断。在交互式终端中，这跳过了前置确认；在 CI 中，这自动上传并将分析打印到 stderr。
—no-扫描	boolean	跳过自动预构建扫描
—扫描忽略致命	boolean	运行预构建扫描，但永远不会阻止构建（仅报告）
—扫描跳过	string	跳过特定扫描检查（可重复或用逗号分隔）。其他检查仍然运行。
—扫描警告	string	将特定扫描检查（可重复或用逗号分隔）降级为警告。检查仍然运行。
—在警告时失败	boolean	将扫描警告视为致命
—将日志发送到支持	boolean	在CI/CD构建失败时，自动上传构建日志到Capgo支持（无需电子邮件）。Capgo支持将收到通知并通过电子邮件跟进。—ai分析是可加性的
—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	—path
—check	boolean	—check

🔹 Prescan

npx @capgo/cli@latest build prescan

扫描您的项目和保存的凭据，找出可能会导致云构建失败的问题 —— 在上传任何内容之前。 检查凭据（有效期，密码，配置文件配对），项目状态（cap 同步，node_modules 布局），和平台配置。自动在此命令中运行（例如，在 CI 中）。 请参见 build request预扫检查 查看完整的检查目录和如何 个别规则。 --skip / --warn 选项：

参数

类型	context	Description
—平台	string	目标平台：ios 或 android（必填）
—路径	string	项目目录路径（默认：当前目录）
-a	string	API 用于链接到您的账户
—android-flavor	string	Android：构建将使用的产品风格
—ios-dist	string	iOS：用于验证的分发模式
—json	boolean	输出机器可读的 JSON 报告
—fail-on-warnings	boolean	在 CI 环境下，遇到警告时退出非零状态
—ignore-fatal	boolean	诊断模式：报告所有信息但总是退出 0
—skip	string	跳过特定检查（可重复或用逗号分隔）
—warn	string	将特定检查（可重复或用逗号分隔）降级为警告
—verbose	boolean	启用详细日志输出
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
———	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

选项：

参数	类型	Description
——路径	string	路径到由 —output-record 写的 JSON 记录（必填）
——字段	string	打印一个字段（其中之一：jobId，appId，platform，buildMode，status，outputUrl，qrCodeAscii，qrCodePngPath，finishedAt，schemaVersion）
——二维码	boolean	打印渲染的 ASCII 二维码 code（—field qrCodeAscii 的快捷方式）

🔹 凭证

管理本地机器上存储的构建凭证。 🔒 安全性：

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

🔹 Apple-key

Alias: 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:

选项:

参数	类型	关于Capgo页面
描述	string	API 关键字链接到您的账户
—appId	string	--appId
—local	boolean	将配置保存到每个项目的 .capgo-credentials.json 文件中，而不是全局文件
—json	boolean	打印捕获的 Key ID / Issuer 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 秘钥 ./AuthKey.p8 —apple 秘钥 ID “KEY123”
  —apple 发行者 ID “issuer-uuid” —apple 团队 ID “team-id” 多目标示例 (app + 小工具扩展): npx @capgo/cli build credentials save —平台 ios
  —ios 配置文件 ./App.mobileprovision
  —ios 配置文件 com.example.widget=./Widget.mobileprovision
  … npx @capgo/cli build credentials save —平台 android
  —keystore ./release.keystore —keystore 别名 “my-key”
  —keystore 秘钥密码 “key-pass”
  —play 配置 ./service-account.json 本地存储 (per-project): npx @capgo/cli build credentials save —本地 —平台 ios …

示例：

iOS Example:

选项:

参数	类型	描述
—appId	string	应用程序ID（例如，com.example.app）（必填）
—platform	string	平台：ios 或 android（必填）
—certificate	string	iOS：.p12证书文件路径
—ios-provisioning-profile	string	iOS: 证书配置文件路径或bundleId=path (可重复)
—p12-password	string	iOS: 证书密码 (如果证书没有密码则可选)
—apple-key	string	iOS: .p8 App Store Connect API key路径
—apple-key-id	string	iOS: App Store Connect API 应用密钥 ID
—apple-issuer-id	string	iOS: App Store Connect 发行者 ID
—apple-team-id	string	iOS: App Store Connect Team 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（需要与 —apple-id 和 —apple-app-specific-password 一起使用）
—keystore	string	Android: Keystore 文件路径 (.keystore 或 .jks)
—keystore-alias	string	Android: Keystore 密钥别名
—keystore-key-password	string	Android: Keystore 密钥密码
—keystore-store-password	string	Android: Keystore 存储密码
—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/
—output-upload	boolean	将 Capgo 存储中的构建输出 (IPA/APK/AAB) 上传并打印下载链接
—不上传构建输出 (IPA/APK/AAB)	boolean	不上传构建输出 (IPA/APK/AAB) 到 Capgo 存储
—输出保留期限	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 # 列出特定应用

选项：

参数	类型	context
类型	string	描述
—本地	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

选项：

参数	类型	context
—appId	string	应用 ID（可选，清除所有应用时省略)
—平台	string	平台：ios 或 android（可选，清除所有平台时省略)
—本地	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	证书文件路径
—ios-配置文件	string	配置文件路径或bundleId=path（可重复，按加法默认）
—覆盖iOS配置映射	boolean	取代整个配置映射而不是合并（默认：合并）
—p12密码	string	P12证书密码
—苹果密钥	string	App Store Connect密钥API路径(.p8文件)
—苹果密钥ID	string	App Store Connect密钥IDAPI
—苹果发行者ID	string	App Store Connect发行者ID
—苹果团队ID	string	App Store Connect团队ID
—apple-id	string	iOS: Apple ID邮箱（用于app特定密码上传）(App Store Connect API key的替代)
—apple-app-specific-password	string	iOS: App特定密码（xxxx-xxxx-xxxx-xxxx）用于TestFlight上传
—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	Keystore密钥别名
—keystore-key-password	string	Keystore key 密码
—keystore-store-password	string	Keystore store 密码
—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 存储并打印下载链接
—无输出上传	boolean	不上传构建输出（IPA/APK/AAB）到Capgo存储
—输出保留	string	输出链接TTL：1小时至7天。示例：1小时，6小时，2天
—跳过构建号码增加	boolean	跳过自动构建号码/版本code增加
—不跳过构建号码增加	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

选项：

参数	类型	Description
描述	string	appId选项值（可选，若省略则会提示选择）
—平台	string	选择管理的平台：ios 或 android（可选，若省略则会提示选择)
—本地	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 )
—local	boolean	从本地 .capgo-credentials.json 迁移而不是全局