跳转到正文

🔹 Build

🏗️ 通过 Capgo Cloud 管理原生 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

传入 --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

🧭 如果需要 Native Build,则打印 “yes” 并以 code 1 退出;否则打印 “no” 并以 code 0 退出。命令失败时以 code 2 退出。

示例:

终端窗口
npx @capgo/cli@latest build needed com.example.app --channel production --verbose

选项:

参数类型描述
-astringAPI 用于关联您的账户的密钥
-cstring要对比的 Channel。默认为 CapacitorUpdater.defaultChannel 或公共默认 Channel
—package-jsonstringMonorepo 中 package.json 文件的路径(以逗号分隔)
—node-modulesstringMonorepo 中 node_modules 目录的路径(以逗号分隔)
—verboseboolean启用详细日志输出
—supa-hoststring自定义 Supabase host URL(用于自托管或 Capgo 开发)
—supa-anonstring自定义 Supabase anon key(用于自托管)

别名: onboarding

终端窗口
npx @capgo/cli@latest build init

以交互方式设置 build 凭据(iOS:自动配置证书和描述文件;Android:keystore + Google OAuth,用于配置 GCP 服务账号并发送 Play Console 邀请)

选项:

参数类型描述
-astringAPI 用于关联您的账户的密钥
-pstring要执行 onboarding 的平台(ios 或 android)。省略时,如果只有一个原生文件夹会自动检测;否则会提示选择。
—supa-hoststring自定义 Supabase host URL(用于自托管或 Capgo 开发)
—no-analyticsboolean本次运行禁用 build onboarding analytics 和 terminal replay
终端窗口
npx @capgo/cli@latest build request

从 Capgo Cloud 请求 Native Build。 该命令会将你的项目目录打包成 zip 文件并上传到 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 .

选项:

参数类型描述
—pathstring要构建的项目目录路径(默认:当前目录)
—node-modulesstringMonorepo 中 node_modules 目录的路径(以逗号分隔)
—platformstring目标平台:ios 或 android(必填)
—build-modestring构建模式:debug 或 release(默认:release)
—build-certificate-base64stringiOS:Base64 编码的 .p12 证书
—p12-passwordstringiOS:证书密码(证书无密码时可选)
—apple-idstringiOS:使用 App 专用密码上传时所需的 Apple ID 邮箱(可替代 App Store Connect API key)
—apple-app-specific-passwordstringiOS:用于 TestFlight 上传的 App 专用密码 (xxxx-xxxx-xxxx-xxxx)
—apple-app-idstringiOS:App Store Connect 数字 App ID(需与 —apple-id 和 —apple-app-specific-password 一起使用)
—apple-key-idstringiOS:App Store Connect API Key ID
—apple-issuer-idstringiOS:App Store Connect Issuer ID
—apple-key-contentstringiOS:Base64 编码的 App Store Connect API 密钥(.p8)
—app-store-connect-team-idstringiOS:App Store Connect 团队 ID
—ios-schemestringiOS:用于 build 的 Xcode scheme(默认:App)
—ios-targetstringiOS:用于读取 build 设置的 Xcode target(默认:与 scheme 相同)
—xcode-versionstringiOS:在具有此 Xcode 版本的机器上 build(例如 26、26.0.1、27)。主版本可接受任意次版本。默认:任意机器。优先级:CLI > 环境变量(CAPGO_IOS_XCODE_VERSION)> 已保存的凭据
—ios-distributionstringiOS:分发模式
—ios-provisioning-profilestringiOS:描述文件路径或 bundleId=path 映射(可重复)
—android-keystore-filestringAndroid:Base64 编码的 keystore 文件
—keystore-key-aliasstringAndroid:Keystore 密钥别名
—keystore-key-passwordstringAndroid:Keystore 密钥密码
—keystore-store-passwordstringAndroid:Keystore 密钥库密码
—play-config-jsonstringAndroid:Base64 编码的 Google Play 服务账号 JSON
—android-flavorstringAndroid: 要构建的 Product flavor(例如 production)。如果项目包含多个 flavor,则此项必填。
—android-trackstringAndroid: 本次上传对应的 Google Play track(internal, alpha, beta, production)。若未指定 —submit-to-store-review,默认值为 internal;若指定了 —submit-to-store-review 且未设置 track,则为 production。优先级:CLI > env > 已保存的凭据
—android-release-statusstringAndroid: Google Play 发布状态(draft, completed, inProgress, halted)。若未指定 —submit-to-store-review,默认值为 draft;若指定了 —submit-to-store-review 且未设置 status,则为 completed。优先级:CLI > env > 已保存的凭据
—in-app-update-prioritystringAndroid: 本次发布的 Google Play 应用内更新优先级(整数 0–5;数值越高越紧急)。详见 https://developer.android.com/guide/playcore/in-app-updates。优先级:CLI > env > 已保存的凭据
—no-playstore-uploadboolean跳过本次构建的 Play Store 上传(会将已保存的 Play 配置置空)。需要配合 —output-upload 使用。
—submit-to-store-reviewboolean上传后,将商店发布提交审核,而不是让它停留在草稿/未激活构建状态。在 Android 上,默认提交到 production 轨道,release_status 为 completed(可用 —android-track / PLAY_STORE_TRACK 和 —android-release-status / PLAY_STORE_RELEASE_STATUS 覆盖)。在 iOS 上,会将处理完成的 TestFlight 构建提交至 App Store 审核。
—store-release-namestring商店发布名称/版本标签。Android 会将其作为 Google Play 的 version_name 发送;iOS 在创建或复用可编辑版本时,将其用作 App Store 版本。
—store-release-notesstring默认商店发布说明。Android 将其用作 Play 更新日志;iOS 将其用作 App Store“新功能”文本的备用内容。
—store-release-notes-localestring本地化商店发布说明(可重复指定),例如 —store-release-notes-locale en-US=“Bug fixes” —store-release-notes-locale fr-FR=“Corrections”。
—ios-testflight-groupsstringiOS:可选,逗号分隔的 TestFlight 外部测试组名称或 ID,用于外部 Beta 分发。
—ios-automatic-releasebooleaniOS:Apple 审核通过后自动发布 App Store 版本。默认为手动发布。
—no-ios-automatic-releasebooleaniOS:Apple 审核通过后,让 App Store 版本保持待手动发布状态。
—output-uploadboolean仅针对本次 build 覆盖输出上传行为(启用)。优先级:CLI > 环境变量 > 已保存的凭据
—no-output-uploadboolean仅针对本次 build 覆盖输出上传行为(禁用)。优先级:CLI > 环境变量 > 已保存的凭据
—output-retentionstring仅针对本次 build 覆盖输出链接的 TTL(1h 至 7d)。示例:1h、6h、2d。优先级:CLI > 环境变量 > 已保存的凭据
—output-recordstringbuild 成功后,将 JSON 记录(jobId、status、outputUrl、qrCodeAscii、qrCodePngPath、finishedAt)写入指定路径。同时会在该路径旁写入一个 PNG QR code,并带有 .qr.png 后缀。读回字段请使用 build last-output.
—no-cacheboolean跳过构建缓存恢复 以及 本次构建不保存新的缓存条目。每个 App 默认启用构建缓存。
—cache-keystring按环境、分支或 Android flavor 划分构建缓存(例如 prod, staging)。省略则每个 App 共用一个默认缓存。
—no-skip-build-number-bumpboolean覆盖已保存的凭据,仅本次构建重新启用 build number 自动递增。
—skip-marketing-version-bumpboolean当 App 已发布时,跳过自动递增营销版本号(CFBundleShortVersionString / versionName)。
—sync-ios-versionbooleaniOS:上传项目前,从 package.json 同步 Xcode 的 MARKETING_VERSION。
—ai-analyticsboolean构建失败时,将日志发送给 Capgo AI 进行诊断。在交互式终端中,这会跳过前置确认;在 CI 中则自动上传,并将分析结果输出到 stderr。
—no-prescanboolean跳过自动构建前扫描
—prescan-ignore-fatalboolean运行构建前扫描,但绝不阻塞构建(仅报告)
—prescan-skipstring按 ID 跳过特定的 prescan 检查项(可重复指定或用逗号分隔)。其他检查仍会运行。
—prescan-warnstring按 ID 将特定的 prescan 检查项降级为警告(可重复指定或用逗号分隔)。检查仍会运行。
—fail-on-warningsboolean将 prescan 警告视为致命错误
—send-logs-to-supportbooleanCI/CD 构建失败时,自动将构建日志上传至 Capgo 支持团队(无需提供邮箱)。Capgo 支持团队会收到通知并通过邮件跟进。此功能与 —ai-analytics 叠加使用。
—send-logsboolean—send-logs-to-support 的已弃用别名
-astringAPI 用于关联您的账户的密钥
—supa-hoststring自定义 Supabase host URL(用于自托管或 Capgo 开发)
—supa-anonstring自定义 Supabase anon key(用于自托管)
—verboseboolean启用详细日志输出

构建缓存: Capgo 默认按应用恢复并保存编译后的原生产物(CocoaPods、Gradle 及相关输出)。使用 --cache-key 以隔离 RC 和生产环境的缓存;使用 --no-cache 执行一次性干净构建。API 集成可在构建请求负载中传递 cache_key 或 cache_enabled: false 。参见 构建缓存 以及 故障排除:缓存恢复错误.

终端窗口
npx @capgo/cli@latest build sync-ios-version

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

示例:

终端窗口
npx @capgo/cli@latest build sync-ios-version --path .

选项:

参数类型描述
—pathstring项目目录路径(默认:当前目录)
—checkboolean仅检查;当 MARKETING_VERSION 不同步时以非零状态退出
终端窗口
npx @capgo/cli@latest build prescan

扫描您的项目和已保存的凭据,查找会导致云端构建失败的问题——在上传任何内容之前。 检查凭据(有效期、密码、配置文件配对)、项目状态(cap sync、node_modules 布局)以及平台配置。在内部自动运行 build request;此命令可独立运行(例如在 CI 中)。 参见 预扫描检查 以获取完整的检查目录以及如何 --skip / --warn 单独规则。

选项:

参数类型描述
—platformstring目标平台:ios 或 android(必填)
—pathstring项目目录路径(默认:当前目录)
-astringAPI 用于关联您的账户的密钥
—android-flavorstringAndroid:构建时使用的 product flavor
—ios-diststringiOS:用于校验的 distribution mode
—jsonboolean输出机器可读的 JSON 报告
—fail-on-warningsboolean发现警告时以非零状态退出(CI)
—ignore-fatalboolean诊断模式:报告所有问题,但始终返回 0
—skipstring按 ID 跳过特定检查(可重复使用或逗号分隔)
—warnstring按 ID 将特定检查降级为警告(可重复使用或逗号分隔)
—verboseboolean启用详细日志输出
—supa-hoststring自定义 Supabase host URL(用于自托管或 Capgo 开发)
—supa-anonstring自定义 Supabase anon key(用于自托管)
终端窗口
npx @capgo/cli@latest build last-output

读取上一次写入的构建输出记录 build request --output-record. 默认输出完整 JSON,使用 —field 输出单个字段,或使用 —qr 输出 ASCII QR code。在 CI 中很方便,可抓取下载 URL 或 QR 码,回帖到 PR 或 issue。 示例: 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

选项:

参数类型描述
—pathstring由 —output-record 写入的 JSON 记录路径(必填)
—fieldstring打印单个字段(可选值:jobId, appId, platform, buildMode, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt, schemaVersion)
—qrboolean打印渲染后的 ASCII QR code(—field qrCodeAscii 的快捷方式)

管理存储在本机的 build 凭据。 🔒 安全:

别名: asc-key

终端窗口
npx @capgo/cli@latest build credentials apple-key

通过 macOS 引导助手创建 App Store Connect 团队 API 密钥(仅限 macOS)。 它会打开一个原生窗口,在嵌入式浏览器中引导你完成 Apple App Store Connect 的 UI 操作,自动获取 Issuer ID + Key ID,拦截一次性的 .p8 文件,向 Apple 进行验证,并将其保存至 ~/.appstoreconnect/private_keys。 进度统计数据会发送至 Capgo 进行分析(可通过 CAPGO_DISABLE_TELEMETRY 禁用)。 npx @capgo/cli build credentials apple-key —appId com.example.app

示例:

终端窗口
Example:

选项:

参数类型描述
-astringAPI 用于关联您的账户的密钥
—appIdstring将捕获的密钥保存到此应用的 iOS 构建凭据中
—localboolean将凭据保存到项目内的 .capgo-credentials.json,而非全局文件
—jsonboolean以 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 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” 多目标示例(应用 + 小组件扩展): npx @capgo/cli build credentials save —platform ios
    —ios-provisioning-profile ./App.mobileprovision
    —ios-provisioning-profile 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:

选项:

参数类型描述
—appIdstringApp ID(例如 com.example.app)(必填)
—platformstring平台:ios 或 android(必填)
—certificatestringiOS:.p12 证书文件路径
—ios-provisioning-profilestringiOS:描述文件路径或 bundleId=路径(可重复)
—p12-passwordstringiOS:证书密码(证书无密码时可选)
—apple-keystringiOS:.p8 App Store Connect API 密钥路径
—apple-key-idstringiOS:App Store Connect API Key ID
—apple-issuer-idstringiOS:App Store Connect Issuer ID
—apple-team-idstringiOS:App Store Connect 团队 ID
—ios-distributionstringiOS:分发模式
—apple-idstringiOS:使用 App 专用密码上传时所需的 Apple ID 邮箱(可替代 App Store Connect API key)
—apple-app-specific-passwordstringiOS:用于 TestFlight 上传的 App 专用密码 (xxxx-xxxx-xxxx-xxxx)
—apple-app-idstringiOS:App Store Connect 数字 App ID(需与 —apple-id 和 —apple-app-specific-password 一起使用)
—keystorestringAndroid:密钥库文件路径(.keystore 或 .jks)
—keystore-aliasstringAndroid:Keystore 密钥别名
—keystore-key-passwordstringAndroid:Keystore 密钥密码
—keystore-store-passwordstringAndroid:Keystore 密钥库密码
—play-configstringAndroid:Play Store 服务账号 JSON 路径
—android-flavorstringAndroid: 要构建的 Product flavor(例如 production)。如果项目包含多个 flavor,则此项必填。
—in-app-update-prioritystringAndroid:Google Play 未来版本的应用内更新优先级(整数 0–5;数值越高越紧急)。省略则保持 Play 现有值不变。
—localboolean保存到项目根目录下的 .capgo-credentials.json,而不是全局的 ~/.capgo-credentials/
—output-uploadboolean将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储并打印下载链接
—no-output-uploadboolean不要将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储
—output-retentionstring输出链接 TTL:1h 至 7d(默认:1h)。示例:1h、6h、2d
—skip-build-number-bumpboolean在后续构建中跳过 build number/version code 的自动递增
—no-skip-build-number-bumpboolean重新启用 build number 自动递增(默认行为)
—skip-marketing-version-bumpboolean当应用已发布时,跳过未来构建中的自动营销版本号递增
—no-skip-marketing-version-bumpboolean重新启用自动递增营销版本号(默认行为)
终端窗口
npx @capgo/cli@latest build credentials list

列出已保存的构建凭据(密码已掩码)。 显示当前保存的凭据(包括全局和本地)。 示例: npx @capgo/cli build credentials list # 列出所有应用 npx @capgo/cli build credentials list —appId com.example.app # 列出特定应用

选项:

参数类型描述
—appIdstring要列出的 App ID(可选,省略则列出全部)
—localboolean仅列出本地 .capgo-credentials.json 中的凭据
终端窗口
npx @capgo/cli@latest build credentials clear

清除已保存的 build 凭据。 从存储中移除凭据。 使用 —appId 和 —platform 指定要操作的凭据。 示例: npx @capgo/cli build credentials clear # 清除所有 App(全局) npx @capgo/cli build credentials clear —local # 清除本地凭据 npx @capgo/cli build credentials clear —appId com.example.app —platform ios

选项:

参数类型描述
—appIdstring要清除的 App ID(可选,省略则清除所有应用)
—platformstring要清除的平台:ios 或 android(可选,省略则清除所有平台)
—localboolean从本地 .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

选项:

参数类型描述
—appIdstringApp ID(如果省略,将从 capacitor.config 中自动检测)
—platformstring平台:ios 或 android(根据选项自动检测)
—localboolean更新本地 .capgo-credentials.json 而非全局配置
—certificatestringP12 证书文件路径
—ios-provisioning-profilestringProvisioning profile 路径或 bundleId=path(可重复指定,默认累加)
—overwrite-ios-provisioning-mapboolean替换整个 provisioning map 而非合并(默认:合并)
—p12-passwordstringP12 证书密码
—apple-keystringApp Store Connect API 密钥路径(.p8 文件)
—apple-key-idstringApp Store Connect API 密钥 ID
—apple-issuer-idstringApp Store Connect 颁发者 ID
—apple-team-idstringApp Store Connect 团队 ID
—apple-idstringiOS:使用 App 专用密码上传时所需的 Apple ID 邮箱(可替代 App Store Connect API key)
—apple-app-specific-passwordstringiOS:用于 TestFlight 上传的 App 专用密码 (xxxx-xxxx-xxxx-xxxx)
—apple-app-idstringiOS:App Store Connect 数字 App ID(需与 —apple-id 和 —apple-app-specific-password 一起使用)
—ios-distributionstringiOS:分发模式
—keystorestringkeystore 文件路径(.keystore 或 .jks)
—keystore-aliasstringKeystore 密钥别名
—keystore-key-passwordstringKeystore 密钥密码
—keystore-store-passwordstringKeystore 存储密码
—play-configstringGoogle Play 服务账号 JSON 文件路径
—android-flavorstringAndroid: 要构建的 Product flavor(例如 production)。如果项目包含多个 flavor,则此项必填。
—in-app-update-prioritystringAndroid:Google Play 应用内更新优先级,用于后续版本(整数 0–5;数值越高越紧急)。
—output-uploadboolean将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储并打印下载链接
—no-output-uploadboolean不要将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储
—output-retentionstring输出链接 TTL:1h 至 7d。示例:1h, 6h, 2d
—skip-build-number-bumpboolean在后续构建中跳过 build number/version code 的自动递增
—no-skip-build-number-bumpboolean重新启用 build number 自动递增(默认行为)
—skip-marketing-version-bumpboolean当应用已发布时,跳过未来构建中的自动营销版本号递增
—no-skip-marketing-version-bumpboolean重新启用自动递增营销版本号(默认行为)
终端窗口
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

选项:

参数类型描述
—appIdstring要管理的 App ID(可选,省略时会提示选择)
—platformstring要管理的平台:ios 或 android(可选,省略时会提示选择)
—localboolean仅浏览本地 .capgo-credentials.json
终端窗口
npx @capgo/cli@latest build credentials migrate

将旧版 provisioning profile 迁移到新的多目标格式。 将 BUILD_PROVISION_PROFILE_BASE64 转换为 CAPGO_IOS_PROVISIONING_MAP。 自动从 Xcode 项目中识别主 bundle ID。 npx @capgo/cli build credentials migrate —platform ios

示例:

终端窗口
Example:

选项:

参数类型描述
—appIdstringApp ID(若省略,将从 capacitor.config 中自动检测)
—platformstring平台(仅支持 ios)
—本地boolean从本地 .capgo-credentials.json 迁移,而非全局文件