命令

本页是引导式概览。确切 flag 请以最新命令参考为准： 应用, bundle, channel，以及 build.

使用情况

所有命令都应在应用目录下运行，并确保 capacitor 项目已正确初始化。

Capacitor 面向 Web 应用的跨平台原生运行时

初始化

npx @capgo/cli@latest init [apikey]

此方法将引导你完成逐步 onboarding。

它会将你的应用添加到 Capgo。它会在应用中添加 code 以验证更新。同时，它会构建你的应用。此外，它还会将应用 upload 到 Capgo，并帮助你检查更新是否生效。

登录

npx @capgo/cli login [apikey]

此方法用于记录 apikey 来为你完成操作。

注意

使用 --apikey=******** 在任何命令中以覆盖它

你可以选择提供：

--local 这将把你的 apikey 存储在本地仓库中，并将其加入 git ignore。

Doctor

npx @capgo/cli doctor

检查 Capgo 包是否为最新版本的命令。

该命令在提交 bug report 时也非常有用。

应用

添加

npx @capgo/cli app add [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

💡 如果未提供，所有选项都将根据您的配置自动推断。

你还可以选择提供：

• --icon [/path/to/my/icon] 以便在 Capgo web app 中显示自定义图标。
• --name [test] 以便在列表中显示自定义名称。
• --apikey [key] 用于关联你账户的 API 密钥。
• --retention [retention] app bundle 的保留天数，默认为 0 = 永久保留。

示例： capacitor.config.json 对于 appId 和 AppName，图标将从 resources 文件夹中自动推断

{
  "appId": "ee.forgr.capacitor_go",
  "appName": "Capgo",
  "webDir": "dist"
}

设置

npx @capgo/cli app set [appId]

[appId] 是您的 App ID，格式说明见下文 这里.

你还可以选择提供：

• --icon [/path/to/my/icon] 以便在 Capgo web app 中显示自定义图标。
• --name [test] 以便在列表中显示自定义名称。
• --retention [retention] app bundle 的保留天数，默认为 0 = 无限期。
• --expose-metadata [true|false] 将 bundle 元数据（链接和注释）暴露给 plugin。
• --preview 或 --no-preview 启用或禁用 bundle 和 channel 的预览二维码。
• --allow-device-custom-id 或 --no-allow-device-custom-id 用于控制自定义 device IDs。
• --block-provider-infra-requests 或 --no-block-provider-infra-requests 用于控制是否拦截已知的 Google 和 Apple 数据中心请求。
• --build-timeout-minutes [5-360] 用于设置 Native Build 超时时间。
• --ios-store-url [url] 或 --android-store-url [url] 用于设置应用商店 URL。
• --default-upload-channel [channel] 用于设置默认的 upload channel。
• --default-download-channel [channel] 用于设置默认的 download channel，或者 --disable-download-channels 将所有 download channels 设置为非公开。
• --apikey [key] 用于关联你账户的 API 密钥。

列出

npx @capgo/cli app list [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。

删除

npx @capgo/cli app delete [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。
• --bundle 指定版本号时，只会删除该版本。

调试

npx @capgo/cli app debug [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。
• --device 使用您想要调试的具体设备

设置

npx @capgo/cli app setting [path]

编辑 Capacitor 配置。

[path] - 您想要更改的设置路径。例如，要更改 appId，提供 appId。 如果你想在 capacitor-updater，提供 plugins.CapacitorUpdater.autoUpdate 配合 --string off.

你必须提供以下之一： --string 或 --bool!

选项：

• --string <string> - 将设置设为字符串
• --bool <true | false> - 将设置设为布尔值

Bundle

上传

npx @capgo/cli bundle upload [appId]

[appId] 是您的 App ID，格式说明见下文 这里.

你还可以选择提供：

• --apikey <apikey> 用于关联你账户的 API 密钥。
• --path <path> 要上传的文件夹路径。
• --channel <channel> 要关联的 Channel。
• --external <url> 链接到外部 URL，而不是上传到 Capgo Cloud。
• --iv-session-key <key> 为外部 bundle URL 设置 IV 和 session key。
• --s3-endpoint <s3Endpoint> S3 端点 URL。不适用于 delta 上传或 external 选项。
• --s3-region <region> S3 bucket 所在的 Region。
• --s3-apikey <apikey> S3 端点的 API key。
• --s3-apisecret <apisecret> 用于 S3 端点的 API 密钥。
• --s3-bucket-name <bucketName> AWS S3 bucket 的名称。
• --s3-port <port> S3 端点的端口号。
• --no-s3-ssl 禁用 S3 upload 的 SSL。
• --key <key> 公钥自定义路径 (v1 系统)。
• --key-data <keyData> 公钥 (v1 系统)。
• --key-v2 <key> 私钥自定义路径 (v2 系统)。
• --key-data-v2 <keyData> 私钥 (v2 系统)。
• --bundle-url 将 bundle URL 打印到 stdout。
• --no-key 忽略签名密钥，发送明文更新。
• --no-code-check 忽略检查 code 源码中是否调用了 notifyAppReady() 以及根目录是否存在 index。
• --display-iv-session 在控制台显示用于加密更新的 IV 和 session key。
• --bundle <bundle> 要上传的 bundle 版本号。
• --auto-bump [level] 自动递增：基于 channel 关联的 bundle，否则基于最新的远程 App 版本。Level: major, minor (默认), patch (别名 fix), metadata，或 ai (Workers AI 会将本地文件与之前的 Capgo/channel 增量清单进行对比，推断 level 并记录简短原因；若无之前的 Capgo 版本，则跳过 AI 并递增 patch （若无之前的 Capgo 版本）。会自动递增版本号，直到找到可用的名称（已删除的名称仍会被占用）。不能与以下命令组合使用 --bundle.
• --min-update-version <minUpdateVersion> 更新到此版本所需的最低版本。仅在 channel 的自动更新禁用选项设置为 metadata 时生效。
• --auto-min-update-version 根据原生 package 设置最小更新版本。
• --ignore-metadata-check 上传时忽略 metadata (node_modules) 检查。
• --ignore-checksum-check 上传时忽略 checksum 检查。
• --timeout <timeout> 上传过程的超时时间（秒）。
• --delta 在上传完整 bundle 的同时上传 Delta (manifest) 文件。
• --delta-only 仅上传 Delta (manifest) 更新，跳过完整 bundle。
• --no-delta 禁用 Delta (manifest) 上传（如果启用了 instant apply autoUpdate 模式但仍需完整 bundle 时非常有用）。
• --tus 使用 tus 协议上传 bundle。
• --multipart 使用 multipart 协议上传数据至 S3，已弃用，请改用 TUS。
• --encrypted-checksum <encryptedChecksum> 加密校验和（签名）。仅在上传外部 bundle 时使用。
• --package-json <packageJson> package.json 的路径。适用于 monorepo。
• --auto-set-bundle 在 capacitor.config.json 中设置 bundle。
• --node-modules <nodeModules> node_modules 的路径列表。适用于 monorepo（逗号分隔，例如: ../../node_modules,./node_modules）

⭐️ External 选项可解决两种场景：对隐私敏感的企业级用户（不将 code 发送给第三方）以及大于 200 MB 的应用。开启此设置后，Capgo 仅存储 zip 链接并将其发送给所有应用。

👀 Capgo cloud 永远不会查看链接中的内容（针对 external 选项），也不会查看存储在 code 中的内容。

🔑 你还可以通过加密增加第二层安全防护，这样 Capgo 就无法查看或修改任何内容，也就变成了“无需信任”模式。

示例： package.json 适用于版本

{
  "version": "1.0.2"
}

⛔ 版本号必须大于 “0.0.0”。

💡 别忘了每次发送时都更新版本号；出于安全考虑，版本号不能被覆盖，删除后也不能重复使用。

列出

npx @capgo/cli bundle list [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。

删除

npx @capgo/cli bundle delete [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。
• --bundle 指定版本号时，只会删除该版本。

清理

将主版本 SemVer 范围内的版本上传到 Cloud

npx @capgo/cli bundle cleanup [appId] --bundle=[majorVersion] --keep=[numberToKeep]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。
• --bundle [majorVersion] 您希望针对该版本移除旧包的版本号，它将保留最后一个版本以及 numberToKeep.
• --keep [numberToKeep] 您希望保留的包的数量（默认为 4）。

例如：如果您有从 10.0.1 到 10.0.11 的 10 个版本，并且使用 npx @capgo/cli cleanup [appId] --bundle=10.0.0 它将移除 10.0.1 到 10.0.6。10.0.7 到 10.0.11 将被保留。

如果您总共有 20 个版本，且未提供 bundle number，如下所示： npx @capgo/cli cleanup [appId] --keep=2 它将移除 18 个版本，并保留最后 2 个。

该命令会请求确认，并显示一个包含将要保留和移除内容的表格。

注意

此命令将忽略任何 channel 中当前正在使用的 bundle。

加密

警告：此命令已弃用，并将在下一个大版本中移除。请使用新的加密系统。 npx @capgo/cli bundle encrypt [path/to/zip]

此命令用于您使用外部源存储 code 或用于测试目的。

你还可以选择提供：

--key [/path/to/my/private_key] 您的私钥路径。 --key-data [privateKey] 私钥数据（如果您想使用内联方式）。 该命令将打印您的 ivSessionKey并生成一个加密的 zip 文件，以便配合 upload 命令或 decrypt 命令使用。

V2 加密

npx @capgo/cli bundle encrypt [path/to/zip] [checksum]

当您使用外部源存储 code 或出于测试目的时，请使用此命令。 校验和是 bundle 的 sha256 值（由 —key-v2 生成），用于在解密后验证文件的完整性。 它将使用私钥进行加密，并随 bundle 一起发送。 在 encryption v2 中，校验和已升级为 bundle 的“签名”。

你还可以选择提供：

--key [/path/to/my/private_key] 您的私钥路径。 --key-data [privateKey] 私钥数据，如果您想使用内联方式。 --json 以 JSON 格式输出信息。 该命令将打印您的 ivSessionKeyy 并生成加密的 zip 文件，以便配合 upload 命令或 decrypt 命令使用。

解密

npx @capgo/cli bundle decrypt [path/to/zip] [ivSessionKey]

你还可以选择提供：

--key [/path/to/my/private_key] 您的私钥路径。

--key-data [privateKey] 内联使用时的私钥数据。此命令主要用于测试，它会解密 zip 文件并在控制台打印解密后的 base64 session key。

解密 V2

npx @capgo/cli bundle decryptV2 [path/to/zip] [ivSessionKey]

你还可以选择提供：

--key [/path/to/my/private_key] 私钥的路径。 --key-data [privateKey] 内联使用时的私钥数据。此命令主要用于测试，它会解密 zip 文件并在控制台打印解密后的 base64 session key。 --checksum [checksum] 文件的校验和，用于在解密后验证校验和。

Zip

npx @capgo/cli bundle zip [appId]

[appId] 是您的 App ID，格式说明见下文 这里.

你还可以选择提供：

• --path [/path/to/my/bundle] 上传指定的文件夹。
• --bundle [1.0.0] 设置文件名中的 bundle 版本号。
• --name [myapp] 覆盖文件名。
• --json 以 JSON 格式输出信息。
• --no-code-check 忽略 code 检查并仍然发送 bundle。
• --key-v2 使用新的加密系统。新系统使用更好的校验和来验证文件完整性，因此此项为必需。

兼容性

npx @capgo/cli bundle compatibility [appId] -c [channelName]

[appId] 是您的 App ID，格式说明见下文 这里. [channelName] 要检查的 channel 名称。

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。
• --text 在表格中使用文本而非表情符号
• --channel [channel] 用于检查兼容性的 channel。
• --package-json <packageJson> package.json 的路径。适用于 monorepo
• --node-modules <nodeModules> node_modules 的路径列表。适用于 monorepo（以逗号分隔，例如：../../node_modules,./node_modules）

渠道

添加

npx @capgo/cli channel add [channelName] [appId]

[channelName] 新 channel 的名称，例如 production 或 beta. [appId] 你的 App ID 格式 com.test.app 说明如下 这里.

删除

npx @capgo/cli channel delete [channelName] [appId]

[channelName] 您想要删除的 channel 名称。 [appId] 你的 App ID 格式 com.test.app 说明如下 这里.

列出

npx @capgo/cli channel list [appId]

[appId] 你的 App ID 格式 com.test.app 说明如下 这里.

你还可以选择提供：

• --apikey [key] 用于关联你账户的 API 密钥。

设置

npx @capgo/cli channel set [channelName] [appId]

[appId] 是您的 App ID，格式说明见下文 这里. [channelName] 您想要配置的 channel 名称，例如 production 或 beta.

你还可以选择提供：

• --bundle [1.2.3] 已上传至云端的 app bundle，以便将其与 channel 关联。
• --latest 从以下位置获取 bundle 版本 package.json:version，不能与...配合使用 --bundle.
• --state [ normal | default ] 设置 channel 状态，可以 normal 或 default。需要设置一个 channel default.
• --downgrade 允许该 channel 向设备推送降级版本。
• --no-downgrade 禁止该 channel 向设备推送降级版本。
• --upgrade 允许该 channel 向设备推送升级 (major) 版本。
• --no-upgrade 禁止该 channel 向设备推送升级 (major) 版本。
• --ios 允许该 channel 向 iOS 设备推送版本。
• --no-ios 禁止该 channel 向 iOS 设备推送版本。
• --android 允许该 channel 向 Android 设备推送版本。
• --no-android 禁止该 channel 向 Android 设备推送版本。
• --self-assign 允许设备自动加入此 channel。
• --no-self-assign 禁止设备自动加入此 channel。
• --disable-auto-update STRATEGY 禁用此 channel 的自动更新策略。可选选项为：major、minor、patch、metadata 或 none。
• --apikey [key] 用于关联你账户的 API 密钥。

禁用更新策略

有几种方法可以处理禁用过旧版本的更新。
Capgo 无法更新 native code，因此无法从使用旧版 native code 的版本直接更新到使用新版 native code 的版本。 可以通过以下几种方式实现。

首先， major 策略。它能防止从 native 基线版本进行更新 0.0.0 -> 目标 bundle 1.0.0。major 是高亮显示的数字 (1.0.0 以及 0.0.0).
第二种是 minor 策略。当目标 bundle 的主版本号 (major) 或次版本号 (minor) 与设备的 Native Build 基准版本不一致时，该策略会阻止更新，例如 0.0.0 -> 1.1.0 或 1.1.0 -> 1.2.0.

第三， patch 策略。它作为一种极其严格的模式被添加到 capgo 中。除非你完全理解其工作原理，否则不建议使用。 若要接受更新，必须满足以下条件：

• 目标 bundle 与设备基准版本的主版本号 (major) 相同 version_build
• 目标 bundle 与设备基准版本的次版本号 (minor) 相同 version_build
• 目标 bundle 与设备基准修订号 (patch) 相同 version_build
• 仅版本后缀可以不同，例如预发布版本 ("-beta.2") 或构建元数据 ("+build.2)

以下是允许或拒绝更新的具体场景示例

• 允许 1.0.0-beta.1 -> 1.0.0-beta.2
• 允许 1.0.0+build.1 -> 1.0.0+build.2
• 禁止 1.0.0 -> 1.0.1
• 禁止 1.0.0 -> 1.1.0
• 禁止 1.0.0 -> 2.0.0

The strategy comparison uses the native baseline sent as version_build，而不是当前下载并发送的 bundle version_name.

最后是最复杂的策略。该 metadata 策略。
首先需要了解，在最初启用后，由于 channel 缺少必要的 metadata，更新 将会 将会失败。
如果 channel 缺少 metadata，你会看到如下提示：

如果看到此类提示，说明你需要前往该失败 channel 对应的当前 bundle 并设置 metadata。
首先，确认哪个 channel 失败了。你可以通过查看 misconfigured 列来确认

然后前往失败的 channel 并点击 Bundle number。这会带你进入 bundle 页面。

进入页面后，填写 Minimal update version 字段。该字段应为 semver 格式.
如果你传入的值不符合 semver 规范，将会报错；如果一切正常，你应该会看到如下输出：

现在，你可能并不想每次更新时都手动设置这些数据。幸运的是，CLI 会防止你在缺少这些元数据的情况下发送更新

To properly upload a bundle when using the metadata 你需要传入 --min-update-version 配合 有效的 semver。示例如下：

本指南中介绍的 --min-update-version 并不是实现兼容性的唯一方式。 此外还有 --auto-min-update-version. 其工作原理如下。

首先，它会检查当前已上传到该 channel 的版本。其兼容性检查方式与 bundle compatibility 命令一致。 其次，如果新版本是 100% 兼容的，它会复用 min_update_version 该 channel 中最新版本的 如果不是，则它会设置 min_update_version 为新上传版本的 bundle number。

你总能获知 min_update_version 使用此选项时的具体信息。输出内容如下所示：

如果新版本不兼容，输出内容如下所示：

端到端加密（Trustless）

Capgo 支持端到端加密，这意味着您的 bundle(code) 在发送到云端前会被加密，并在设备上解密。为此，您需要生成 RSA 密钥对，可以使用以下命令生成。

该加密系统结合了 RSA 和 AES：RSA 密钥用于加密 AES 密钥，AES 密钥用于加密文件。

有关加密系统的更多信息，请参阅下文。

加密方案

为您的 App 创建密钥

npx @capgo/cli key create

你还可以选择提供： --force 以覆盖现有密钥。此命令会为您的 App 创建密钥对，并要求您将私钥保存在安全的地方。建议不要将私钥提交到 git，也不要与任何人分享。

在本地测试后，从配置文件中移除密钥，并在 CI 步骤中使用以下命令添加： key save

将密钥保存到 App 配置中

npx @capgo/cli key save

你还可以选择提供：

--key [/path/to/my/public_key] 公钥文件的路径。

--key-data [publicKey] 内联使用的公钥数据。如果你遵循了建议，没有将密钥提交到应用配置中，那么这个命令会非常有用。

CI 集成

为了实现自动化，我建议你创建一个 GitHub action 来完成向我们服务器推送的任务

GitHub action 教程

我们的 Demo App

GitHub - Cap-go/demo-app

别忘了使用你的 API 密钥来配置 CI 环境变量

从 Commands 继续

如果你正在使用 命令 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。