📦 Bundle

📦 在 Capgo Cloud 中管理用于部署的应用 bundle，包括上传、兼容性检查和加密。

⬆️ 上传

别名： u

npx @capgo/cli@latest bundle upload

⬆️ 将新的 app bundle upload 到 Capgo Cloud 以进行分发。 版本号必须 > 0.0.0 且唯一。出于安全考虑，已删除的版本无法再次使用。 External 选项：仅存储 URL 链接（适用于 >200MB 的应用或有隐私要求的场景）。 Capgo 绝不会检查外部内容。建议添加加密以实现无须信任的安全保障。

示例：

npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production,beta

当未传入以下参数时，自动从 channel（或最新的远程 app 版本）递增下一个可用的 semver： --bundle。在以下 CI 场景中非常有用： package.json 已与 Capgo 现有的版本匹配：

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

使用 --auto-bump ai, Capgo Cloudflare Workers AI 会将本地 bundle 文件与上一个 Capgo/channel 的 delta manifest 进行对比并推断 major | minor | patch | metadata, 并在 CLI 日志中打印简短原因。如果不存在上一个 Capgo 版本，则跳过 AI 并将 bump 默认设为 patch 版本.

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
-p	string	要上传的文件夹路径。如果未提供，将使用 capacitor.config 中设置的 webDir
-c	string	要关联的 Channel。多个 Channel 请用逗号分隔，例如 production,beta
—rollout	string	将上传的 bundle 设置为该 Channel 的 rollout 目标，百分比范围为 0 到 100
—stable	boolean	在已配置 rollout 的 Channel 上，替换 stable 回退版本而非设置 rollout 目标
—rollout-percentage-bps	string	以基点 (bps) 设置上传 bundle 的 rollout 百分比，范围为 0 到 10000
—rollout-cache-ttl-seconds	string	Cloudflare rollout 决策缓存的 TTL（秒）
-e	string	链接到外部 URL，而不是上传到 Capgo Cloud
—iv-session-key	string	为外部 bundle URL 设置 IV 和 session key
—s3-region	string	S3 bucket 所在的区域
—s3-apikey	string	API S3 endpoint 的 key
—s3-apisecret	string	API S3 endpoint 的 secret
—s3-endpoint	string	S3 endpoint 的 URL
—s3-bucket-name	string	AWS S3 bucket 名称
—s3-port	string	S3 endpoint 端口
—no-s3-ssl	boolean	禁用 S3 upload 的 SSL
—key-v2	string	私钥自定义路径 (v2 系统)
—key-data-v2	string	私钥 (v2 系统)
—bundle-url	boolean	将 bundle URL 输出到 stdout
—no-key	boolean	忽略签名密钥并发送明文更新
—no-code-check	boolean	忽略检查源码 code 中是否调用 notifyAppReady() 以及根目录是否存在 index
—display-iv-session	boolean	在控制台显示加密更新所用的 IV 和 session key
-b	string	要上传的 bundle 版本号
—auto-bump	string	自动递增版本号。优先基于 channel 关联的 bundle，否则基于最新的远程 app 版本。级别可选：major、minor（默认）、patch（别名 fix）、metadata 或 ai（Workers AI 会根据本地与前一版本 manifest 的差异推断级别；若无前一 Capgo 版本则回退至 patch）。将持续递增直到找到可用名称（已删除的名称仍会被占用）。不能与 —bundle (-b) 组合使用
—link	string	链接到外部资源（例如 GitHub release）
—comment	string	关于此版本的注释，可以是 release note、commit hash、commit message 等。
—min-update-version	string	更新到此版本所需的最低版本。仅当 channel 的 disable auto update 设置为 metadata 时使用。
—auto-min-update-version	boolean	根据 native packages 设置最低更新版本。
—ignore-metadata-check	boolean	上传时忽略元数据 (node_modules) 检查。
—fail-on-incompatible	boolean	当 bundle 与 channel 当前的 native packages 不兼容时，让上传失败（退出码非零），而不是继续上传。在交互式终端中，你仍可以选择 native build；拒绝则失败。不能与 —ignore-metadata-check 组合使用。
—ignore-checksum-check	boolean	上传时忽略 checksum 检查。
—force-crc32-checksum	boolean	强制使用 CRC32 校验和进行 upload（覆盖自动检测）
—timeout	string	upload 过程的超时时间（秒）
—multipart	boolean	[已弃用] 请改用 —tus。使用 multipart 协议进行 S3 upload
—zip	boolean	使用 zip 格式将 bundle upload 到 Capgo cloud（旧版）
—tus	boolean	使用 TUS 协议将 bundle upload 到 Capgo cloud
—tus-chunk-size	string	TUS 可断点续传 upload 的分块大小（字节，默认：auto）
—partial	boolean	[已弃用] 请改用 —delta。上传增量更新
—partial-only	boolean	[已弃用] 请改用 —delta-only。仅上传增量更新，跳过完整 bundle
—delta	boolean	上传 delta 更新（仅包含变更文件），实现即时、极速更新，无需下载大体积 zip 包
—delta-only	boolean	仅上传 delta 更新，不上传完整 bundle，以获得最高速度（适用于大型 App）
—no-delta	boolean	即使启用了即时更新，也禁用 delta 更新
—encrypted-checksum	string	加密校验和（签名）。仅在上传外部 bundle 时使用。
—auto-set-bundle	boolean	在 capacitor.config.json 中设置 bundle
—dry-upload	boolean	模拟 bundle 上传流程：仅在数据库中添加记录，不上传文件或更新 channel（Capgo 用于内部测试）
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）
—node-modules	string	Monorepo 中 node_modules 目录的路径（以逗号分隔）
—encrypt-partial	boolean	加密增量更新文件（updater 版本 > 6.14.4 时自动启用）
—delete-linked-bundle-on-upload	boolean	查找并删除目标 channel 中当前已绑定的 bundle
—no-brotli-patterns	string	要从 Brotli 压缩中排除的文件（逗号分隔的 glob，例如 “.jpg,.png”)
—disable-brotli	boolean	即使 updater 版本支持，也完全禁用 Brotli 压缩
—version-exists-ok	boolean	bundle 版本已存在时以成功状态退出，适用于 monorepo 的 CI/CD 工作流
—self-assign	boolean	允许设备自动加入此 channel（会更新 channel 设置）
—qr-preview	boolean	上传后打印此 bundle 预览的终端 QR code
—send-update-notification	boolean	在更新关联的 channel bundle 后，向设备发送原生更新检查通知
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）
—verbose	boolean	启用详细日志输出

🧪 兼容性

npx @capgo/cli@latest bundle compatibility

🧪 在 Capgo Cloud 中检查 bundle 与特定 channel 的兼容性，确保更新安全。

示例：

npx @capgo/cli@latest bundle compatibility com.example.app --channel production

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
-c	string	用于检查兼容性的 channel
—text	boolean	输出文本而非表情符号
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）
—node-modules	string	Monorepo 中 node_modules 目录的路径（以逗号分隔）
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🔹 ReleaseType

npx @capgo/cli@latest bundle releaseType

🧭 根据与 channel 最新元数据的兼容性，输出 “native” 或 “OTA”。

示例：

npx @capgo/cli@latest bundle releaseType com.example.app --channel production

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
-c	string	用于对比的 Channel
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）
—node-modules	string	Monorepo 中 node_modules 目录的路径（以逗号分隔）
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🗑️ 删除

别名： d

npx @capgo/cli@latest bundle delete

🗑️ 从 Capgo Cloud 中删除特定的 bundle，可选择指定版本。

示例：

npx @capgo/cli@latest bundle delete BUNDLE_ID com.example.app

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

📋 列出

别名： l

npx @capgo/cli@latest bundle list

📋 列出已上传至 Capgo Cloud 的该应用所有 bundles。

示例：

npx @capgo/cli@latest bundle list com.example.app

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🧹 清理

别名： c

npx @capgo/cli@latest bundle cleanup

🧹 删除 Capgo Cloud 中的旧 bundle，仅保留指定数量的最新版本。 除非使用 —ignore-channel 参数，否则与 channel 关联的 bundle 将被保留。

示例：

npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3

选项：

参数	类型	描述
-b	string	要删除的应用的 bundle 版本号
-a	string	API 用于关联您的账户的密钥
-k	string	保留的版本数量
-f	boolean	强制删除
—ignore-channel	boolean	即使已关联 channel 也删除 bundle（警告：channel 也会一并删除）
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🔒 加密

npx @capgo/cli@latest bundle encrypt

🔒 加密 zip bundle，用于安全的外部存储。 返回用于上传/解密的 ivSessionKey。使用 ‘bundle zip —json’ 获取校验和。

示例：

npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

选项：

参数	类型	描述
—key	string	签名私钥的自定义路径
—key-data	string	签名私钥
-j	boolean	以 JSON 格式输出
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）

🔓 解密

npx @capgo/cli@latest bundle decrypt

🔓 解密已加密的 bundle（主要用于测试）。 打印 base64 会话密钥以供验证。

示例：

npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUM

选项：

参数	类型	描述
—key	string	签名私钥的自定义路径
—key-data	string	签名私钥
—checksum	string	Bundle 的校验和，用于验证 Bundle 的完整性
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）

🔹 Zip

npx @capgo/cli@latest bundle zip

🗜️ 将 app bundle 打包成 zip 文件。 返回用于加密的校验和。使用 —json 可获得机器可读输出。

示例：

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

选项：

参数	类型	描述
-p	string	要上传的文件夹路径；未提供时使用 capacitor.config 中设置的 webDir
-b	string	用于命名 zip 文件的 Bundle 版本号
-n	string	zip 文件名
-j	boolean	以 JSON 格式输出
—no-code-check	boolean	忽略检查源码 code 中是否调用 notifyAppReady() 以及根目录是否存在 index
—key-v2	boolean	使用 v2 加密
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）