通道
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Live Update channel 指向你应用的一个特定 JS bundle 版本,所有配置为监听该 channel 以获取更新的设备都将共享该版本。当你 安装 Capgo Live Updates SDK 在应用中,任何配置到该 Channel 的原生二进制都会在应用启动时检查可用更新。你可以随时更改 Channel 指向的 Build,并在需要时回滚到之前的 Build。
Channels 实战案例
“Channels 实战”章节可以把 Channel 看作指向某次更新的命名指针: production 可以在服务已发布应用的同时, beta 为测试人员提供服务。这三段短视频演示了设备如何最终进入某个 Channel。每段视频都有可选背景音乐且无旁白;下面的说明涵盖相同的步骤。
1. 使用默认 Channel
“1. 使用默认 Channel”章节正在运行的设备 v1.1.0 向 Capgo 请求更新。如果没有设备分配或应用内配置的 Channel,Capgo 会检查云端默认 Channel, production并返回其 v1.2.0 bundle。该 dev 以及 staging channel 拥有独立的 bundle,不会影响当前设备。
在以下位置设置您的生产环境默认值 App 信息。常规的 production build 可以保持 defaultChannel 未设置状态,以便您通过 Capgo 管理路由。
2. 让设备自主选择 Channel
标题为“2. 让设备自主选择 channel”的章节本指南使用 setChannel() 以及 unsetChannel() 来自 @capgo/capacitor-updater 在 Android 和 iOS 上运行;这些方法在浏览器中不受支持。它使用了 updater 中可用的 local-channel 行为 5.34.0+, 6.34.0+, 7.34.0+,或 8.0.0+ 针对您插件的主版本。旧版本则是写入后端覆盖;这些赋值遵循 console 和 API 的覆盖保留规则.
测试人员在您的 App 内启用 beta 更新。您的 App 调用 CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true }). Capgo 会检查 beta 允许设备自我分配,然后插件会将该选择保存在本地,以便后续检查更新。其他设备将保持现有的路由。
启用 允许设备在正式使用前 在目标 channel 上自动解绑/绑定 setChannel()。此本地设置不会创建控制台覆盖。在 Android 和 iOS 上,若 updater 版本为 8.51.0 及更高版本, persistDefaultChannelOnReinstall 默认为 true则只有在操作系统恢复应用数据时,该选择才能在重新安装后保留,并且 persistDefaultChannelOnReinstall 保持 true. 调用 unsetChannel() 用于清除本地选择;控制台和 API 覆盖仍遵循以下优先级。
3. 从控制台分配一台设备
标题为 “3. 从控制台分配一台设备”在 Capgo 控制台中,打开 应用,选择您的应用,打开 设备,然后选择一个设备。更改其 Channel 覆盖 改为 dev。. Capgo 现在会将该设备路由至 dev,而应用的云端默认设置仍保持 production.
使用 override 进行定向测试或支持。除非存在强制映射,否则它的优先级高于设备本地 channel 和云端默认值。Console 和 API 的 override 最后一次写入 override 后 90 天过期.
准备好试试了吗? 在 Console 中创建 channel,然后 上传一个 bundle 以供其分发。
设备如何选择 Channel(优先级顺序)
标题为“设备如何选择 Channel(优先级顺序)”的部分当设备检查更新时,Capgo 会按以下严格顺序(优先级从高到低)决定使用哪个 Channel:
- 强制设备映射 (Dashboard) – 手动将特定的设备 ID 绑定到某个 Channel。适用于紧急调试或针对单个真实用户的受控测试。此项优先级最高。Capgo 会在最后一次覆盖写入 90 天后移除该映射。详见 Console 和 API 覆盖将在 90 天后过期.
- 通过 Dashboard 或 API 进行的云端覆盖 (针对单个设备) – 当你在 Dashboard 中或通过 API 更改设备的 Channel 时创建。适用于 QA 用户在功能/PR Channel 之间切换,或用于复现用户问题。重新安装二进制文件不会清除此设置;只有删除设备覆盖设置才会清除。同样适用 90 天保留期。
- 插件
setChannel()本地 Channel – 当 App 调用setChannel()且后端验证目标 Channel 允许自我分配时创建。所选 Channel 会存储在设备的本地,立即生效,且不会显示在 Device Override UI 中。
- Capacitor 配置
defaultChannel(测试构建默认值) – 如果存在于capacitor.config.*且不存在 force/override/local channel 时,App 将启动该 channel(例如beta,qa,pr-123)。这适用于 TestFlight / 内部构建,以便测试人员自动进入预发布 channel。生产环境构建通常保持此项为空。 - Cloud Default Channel(主要路径,覆盖约 99% 的用户) – 如果你在 dashboard 中设置了默认 channel,所有普通终端用户(无 force、无 Dashboard/API 覆盖、无 plugin local channel、无 config defaultChannel)都会连接到此 channel。通过更改它即可实现即时发布或回滚——无需重新构建二进制文件。如果你有特定平台的默认设置(例如,iOS 专用、Android 专用或 Electron 专用),每个设备都会进入与其平台匹配的默认 channel。可以不设置 cloud default;在这种情况下,设备必须满足步骤 1–4 才能接收更新。
最佳实践:
- 将 1–4 视为异常/测试层;当你设置了 cloud default 时,真实用户应当进入该 channel。如果你选择不设置,请务必明确用户连接的方式(通常通过
defaultChannel中的 config 或针对单个设备的 override)。 - 仅在明确分发给测试人员的二进制文件中配置
defaultChannel。保持此项为空可将生产逻辑集中管理在 dashboard 中。 - 使用
setChannel()请谨慎在生产环境中使用——主要用于 QA 或定向诊断。
如果某个频道在原本应被选中时,因平台开关(iOS/Android/Electron)被禁用,则选择过程会跳过该频道并继续向下匹配。
总结:强制 (Force) > Dashboard/API 覆盖 > 插件
setChannel()本地频道 > 配置defaultChannel> Cloud 默认值。
Console 和 API 覆盖将在 90 天后过期
标题为“Console 和 API 覆盖将在 90 天后过期”强制映射以及 Dashboard 或 Public API 频道的覆盖信息,会作为设备级分配存储在 Capgo 中。清理任务会在以下时间删除这些分配: 最后一次写入覆盖信息后的 90 天。检查更新并不会重置该计时器。只有再次写入覆盖信息(或手动删除)才会更新时间戳。
这与以下内容不同: 设备清单的保留策略. Inventory 会移除 90 天未连接过 Capgo 的设备。Override cleanup 则会移除映射,即使设备仍处于活跃状态。
对于不会被此清理移除的 assignment:
- 设置
defaultChannel中的capacitor.config.*(重新安装后仍会保留;之后如需更改,需要新的原生二进制文件)。 - 调用
setChannel()从应用中移除。在 plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本中,该 assignment 保存在本地,不会被此清理移除。在 Android 和 iOS 上,使用 updater 8.51.0 及更高版本时,persistDefaultChannelOnReinstall默认为true,因此只有当操作系统恢复应用数据时,assignment 才能在重新安装后保留,并且persistDefaultChannelOnReinstall保持true. 用于unsetChannel()需要显式清除。
Channel 设备 标签页和设备的 Override UI 仅列出 console 和 Public API 分配。它们不会列出该 channel 上的所有设备,也不会列出本地 setChannel() 分配。

默认 Channel 行为
标题为 “Default Channel Behavior” 的章节设置云端默认值是可选的,但它通常作为新设备的兜底路径。如果没有设置,则只有符合强制映射、overrides 或 defaultChannel Capacitor 配置中规则的设备才会接收更新。当你选择标记默认值时,请记住以下模式:
- 单一默认值(最常见) – 如果一个 channel 启用了 iOS、Android 和 Electron,它将成为唯一的默认值;任何没有 overrides 的设备都将关联至此。
- 平台特定默认值 – 如果你按平台拆分 Channel(例如,
ios-production仅启用 iOS,android-production仅启用 Android,以及electron-production仅启用 Electron),请将每个 Channel 标记为其对应平台的默认值。iOS 设备将使用 iOS 默认值,Android 设备使用 Android 默认值,Electron 应用则使用 Electron 默认值。
请记住,Cloud 默认值与 defaultChannel 中的 capacitor.config.* 处于同一决策层。如果你设置了 Cloud 默认值,则无需在 Capacitor 配置中重复该值——在 defaultChannel 生产环境构建中保持 defaultChannel for binaries you intentionally ship to testers or QA when you want them to start on a non-production channel even if the cloud default is different.
你可以随时在 Dashboard 中更改默认值。打开 Channel,然后 在 App 设置中进行管理,这将带您前往 App 信息。默认设置不再是频道页面上的开关。当您更换默认频道时,新设备会立即遵循新的路由规则,而现有设备将在下次检查更新时遵循常规优先级规则。
设置 Channel
标题为“设置 Channel”的部分在 onboarding 期间,您会创建第一个 channel(大多数团队将其命名为“Production”),但没有任何限制——您可以随时重命名或删除任何 channel。稍后要添加更多 channel:
- 前往 Capgo dashboard 的 “Channels” 部分
- 点击 “New Channel” 按钮
- 输入 channel 名称并点击 “Create”
Channel 名称可以随心定义。一种常见的策略是将 channel 与您的开发阶段相匹配,例如:
Development- 用于在本地设备或模拟器上测试 Live UpdateQA- 用于 QA 团队在广泛发布前验证更新Staging- 用于在类生产环境中进行最终测试Production- 用于终端用户从应用商店获取的应用版本
在应用中配置 Channel
标题为“在应用中配置 Channel”的章节创建好 Channel 后,你需要配置应用监听对应的 Channel。本例中,我们将使用 Development Channel。
打开你的 capacitor.config.ts (或 capacitor.config.json) 文件。在 plugins 部分,可选择设置 defaultChannel 来实现 测试 build (内部 / QA 使用)。生产环境构建建议省略此项,以便设备在未明确覆盖时使用 Cloud Default。
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = { plugins: { CapacitorUpdater: { // For a QA/TestFlight build – testers start on the Development channel automatically. defaultChannel: 'Development', // Production builds usually omit this so users attach to the Cloud Default channel. }, },};接下来,构建您的 Web 应用并运行 npx cap sync 将更新后的配置文件复制到您的 iOS、Android 和 Electron 项目中。如果跳过此同步步骤,您的原生项目将继续使用之前配置的 Channel。
Channel 选项与策略
标题为 “Channel 选项与策略” 的章节Channel 有多个选项,用于控制谁可以接收更新以及更新如何下发。最重要的几个如下。你可以在 Web 应用、CLI 或 Public API 中配置这些选项。
- 默认 Channel:可选择标记新设备加入的 Channel 或特定平台的 Channel。在控制台中,该设置位于 App Information (在 App 设置中管理 在 Channel 页面中)。路由场景请参阅 “Default Channel Behavior”。
- 平台过滤器:启用或禁用向以下平台下发:
iOS,Android,或Electron每个 Channel 的设备。 - Native 下禁用自动降级:当设备的原生 App 版本比 Channel 的 bundle 更新时,阻止发送更新(例如设备为 1.2.3,而 Channel 为 1.2.2)。
- 允许 development build:允许向 development build 发送更新(便于测试)。CLI:
--dev/--no-dev. - 允许生产环境构建:允许向生产环境(商店)构建版本推送更新。面向真实用户的 Channel 请保持开启。CLI:
--prod/--no-prod. - 允许模拟器设备:允许向模拟器/仿真器推送更新(适用于测试)。CLI:
--emulator/--no-emulator. - 允许真机设备:允许向真实的手机和平板推送更新。生产环境 Channel 请保持开启。CLI:
--device/--no-device. - 允许设备自主分配:允许 App 在运行时通过
setChannel切换到此 Channel。如果禁用,setChannel在此 Channel 下将会失败。CLI:--self-assign/--no-self-assign. - 下载格式:选择设备是下载完整的 zip 包、仅下载变更的 delta 文件,还是两者兼顾的(
all,zip,delta,zip_from_builtin,delta_from_builtin)。参见 下载格式 用于控制台下拉菜单,以及说明各模式的适用场景。
Channel 可以保持一个稳定的 bundle,同时向特定的设备群体逐步开放另一个 rollout 目标。你可以在不影响所有用户的情况下,随时暂停、恢复、晋升、回滚,并配置自动故障响应。详情请参阅 渐进式发布 交付模型、dashboard 工作流、API 字段以及 CLI 命令。
禁用 Auto Update 策略
标题为“禁用 Auto Update 策略”的章节使用此项来限制 Channel 自动推送的更新类型。选项:
- major:拦截主版本号高于设备 Native 基线的目标 bundle (
version_build)。示例:1.2.3 -> 2.0.0已被拦截;1.2.3 -> 1.9.0允许通过。 - minor:拦截主版本号或次版本号与以下内容不符的 bundle
version_build。示例:1.2.3 -> 1.3.0被拦截;1.2.3 -> 1.2.4被允许。 - patch:最严格模式。禁止对 major、minor 或 patch 版本号进行任何更改。仅允许后缀变更,而
MAJOR.MINOR.PATCH保持一致。示例: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被拦截。 - metadata:要求每个 bundle 必须包含最小更新版本元数据。通过 CLI 使用
--min-update-version或--auto-min-update-version进行配置。如果缺失,该 channel 会被标记为配置错误,在设置完成前所有更新都将被拒绝。 - none:根据 semver 兼容性允许所有更新.
这些策略会将 Channel 的目标 bundle 与发送的 Native Build 基准进行对比, version_build而不是与当前下载的 bundle 进行对比。 version_name.
更多详情和示例请参阅 /docs/cli/commands/#disable-updates-strategy 中的 Disable updates strategy。
示例 (CLI)。Channel 必须已存在(channel set 系统不会自动创建它):
# Block major updates on the Production channelnpx @capgo/cli@latest channel set production com.example.app \ --disable-auto-update major
# Allow devices to self-assign to the Beta channelnpx @capgo/cli@latest channel set beta com.example.app --self-assign
# Production channel: store builds on real devices, no emulatorsnpx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator在您的 App 中使用 setChannel()
标题为 “Using setChannel() from Your App” 的章节本指南中介绍的 @capgo/capacitor-updater 方法 setChannel() 允许您的 Android 或 iOS App 在运行时通过代码动态切换 Channel。这在以下场景中非常有用:
- 供测试人员切换 Channel 的 QA/调试菜单
- Beta 测试计划的加入流程
- Feature flag 功能实现
- A/B 测试场景
import { CapacitorUpdater } from '@capgo/capacitor-updater';
// Switch to the beta channelawait CapacitorUpdater.setChannel({ channel: 'beta' });
// Optionally trigger an immediate update check after switchingawait CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true});为 Channel 分配 Bundle
标题为“为 Channel 分配 Bundle”的章节要部署 live update,你需要上传新的 JS bundle 构建,并将其分配到一个 channel。使用 Capgo CLI 即可一步完成:
npx @capgo/cli@latest bundle upload --channel=Development这将上传你构建好的 Web 资源,并将新 bundle 设为该 Development channel 的活跃 build。任何配置为监听该 channel 的应用,在下次检查更新时都会收到该更新。
你也可以在 Capgo dashboard 的 “Bundles” 部分中,将 build 分配给 channel。点击 build 旁的菜单图标,选择 “Assign to Channel”,即可为该 build 选择 channel。
Bundle 版本管理与 Channels
“Bundle 版本管理与 Channels” 章节需要注意的是,Capgo 中的 bundle 对你的应用是全局的,并不针对单个 channel。同一个 bundle 可以分配给多个 channel。
为 bundle 设置版本时,我们建议使用 语义化版本控制,配合 Capgo 的 Semver Tester 和预发布标识符来标记特定 channel 的 build。例如,一个 beta 版本可以标记为 1.2.3-beta.1.
在 CI 中,如果本地版本已上传,请使用 npx @capgo/cli@latest bundle upload --auto-bump (可选 major, minor, patch/fix, metadata,或 ai) 因此 CLI 会从 channel 关联的 bundle 开始递增,直到找到可用名称。使用 ai,Workers AI 会根据本地与上一个 delta manifest 的差异推断级别(如果 patch 没有之前的 Capgo 版本,则回退至此)。你不能将其与 --bundle。请参阅 CI/CD 集成 以及 CLI 引用.
这种方法有以下几个优势:
- 它清楚表达了 build 之间的关系。
1.2.3-beta.1显然是……的预发布版本1.2.3. - 它允许跨 channel 复用版本号,减少混淆。
- 它提供了清晰的回滚路径。如果你需要从
1.2.3,你就会知道1.2.2是上一个稳定的版本。
以下是一个典型的 Channel 配置与 Bundle 版本对齐的示例:
Developmentchannel:1.2.3-dev.1,1.2.3-dev.2,等等。QAchannel:1.2.3-qa.1,1.2.3-qa.2,等等。Stagingchannel:1.2.3-rc.1,1.2.3-rc.2,等等。Productionchannel:1.2.3,1.2.4,等等。
使用 带有预发布标识符的 semver 是一种推荐的做法,但并非强制要求。关键在于找到一种版本控制方案,能够清晰地表达各 build 之间的关系,并与您团队的开发流程保持一致。
回滚 Live Update
标题为“回滚 Live Update”的章节如果您部署的 live update 引入了 bug 或需要撤回,可以轻松回滚到之前的 build。在 dashboard 的 “Channels” 部分:
- 点击您想要回滚的 channel 名称
- 找到您想要回滚到的 build,然后点击皇冠图标

- 确认操作
所选的 build 将立即重新成为该 channel 的当前 active build。App 在下次检查更新时将接收到回滚后的版本。
自动化部署
“自动化部署”章节对于更高级的工作流,你可以将 live update 部署集成到 CI/CD pipeline 中实现自动化。通过将 Capgo 集成到构建流程,每当你推送特定分支或创建新 release 时,即可自动 upload 新的 bundle 并将其分配到相应的 channel。
查看 CI/CD 集成 文档以了解更多关于 Capgo Live Update 自动化的信息。
最小权限的 PR 预览
“最小权限 PR 预览”章节使用 应用预览 API key。当 CI 需要为每个 pull request 创建一个临时 channel,但又不能管理现有的 main/default channel 时,请使用此方式。该 key 仍绑定到所属组织和选定的 app,只是不具备组织范围内的角色。它创建的每个非公开预览 channel 都拥有独立的、基于 channel 作用域的自动生命周期权限。
- 让组织管理员创建一个仅限于预览 app 的安全 API key,并选择 应用预览。请参阅 API 密钥.
- 使用唯一的非公开 Channel,例如:
pr-123。请勿传递--default,--self-assign、发布选项或--delete-linked-bundle-on-upload. - 通过一条命令上传并推广 PR bundle,随后在 PR 关闭时删除所属的 Channel 和 bundle:
APP_ID="com.example.app"PREVIEW_CHANNEL="pr-123"BUNDLE_VERSION="1.2.3-pr.123"
npx @capgo/cli@latest bundle upload "$APP_ID" \ --apikey "$CAPGO_PREVIEW_KEY" \ --path ./dist \ --channel "$PREVIEW_CHANNEL" \ --bundle "$BUNDLE_VERSION"
npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \ --apikey "$CAPGO_PREVIEW_KEY" \ --delete-bundle \ --success-if-not-foundbundle upload --channel 在一个流程中自动创建缺失的 Channel、上传 bundle 并进行推广。清理操作具有原子性且经过所有权校验:该 key 只能删除其创建的 Channel 及其关联的、未共享的 bundle。它无法修改、推广或删除现有的 main/default Channel、其他预览 key 的 Channel 或其他 key 的 bundle。
如果审核人员需要 QR code 或预览 URL,管理员必须为该 App 开启一次预览功能:
npx @capgo/cli@latest app set "$APP_ID" --previewnpx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url由于 App Preview 密钥没有 app-settings 权限,它本身无法启用预览。请在 GitHub Actions 中运行包含 secret 的预览任务, pull_request,而不是 pull_request_target,并将其限制为仅同仓库的 PR: github.event.pull_request.head.repo.full_name == github.repository.
部署到设备
标题为“部署到设备”的章节既然你已经了解了 channels,就可以开始向真机部署 Live Update 了。基本流程如下:
- 在应用中安装 Capgo SDK
- 配置应用以监听你指定的 channel
- 上传 build 并将其分配到该 channel
- 启动应用,然后等待更新!
如需更详细的步骤指南,请参阅 部署 Live Updates 指南。祝更新愉快!
Channel 进阶用法:用户分层
章节标题:“高级频道用法:用户分层”Channels 的用途不仅限于开发阶段。它们也是用户分层的强大工具,可以实现以下功能:
- 针对不同用户层级的 Feature flags
- A/B 测试
- 功能的逐步发布 (Gradual rollouts)
- Beta 测试计划
在我们的指南中学习如何实现这些高级用例: 如何根据方案和 Channels 进行用户分层,以实现 Feature Flags 和 A/B testing.
继续探索 Channels
章节标题:“更多关于 Channels 的内容”如果你正在使用 通道 要规划 Channel 路由和分阶段发布,请将其与 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, Beta 测试解决方案 有关 Beta 测试解决方案的产品工作流, 版本定向解决方案 有关版本定向解决方案的产品工作流,以及 Capgo 环境最佳实践:使用一个 Mobile App ID 进行 Staging 有关 Capgo 环境最佳实践:使用一个 Mobile App ID 进行 Staging 的实际场景。