跳转到正文

通道

初次接触渠道? 观看三个简短的频道演示视频 了解默认路由、设备自行分配和控制台覆盖的实际效果。

本指南中介绍的 @capgo/capacitor-updater 方法 setChannel() 以及 unsetChannel() 仅支持 Android 和 iOS。它们不会改变浏览器预览中的频道路由。

当设备向 Capgo 请求更新时,会按以下顺序决定使用哪个频道(优先级从高到低):

  1. 强制设备映射:如果设备 ID 被显式强制映射到某个频道( 设备 通道页面上的标签),该通道始终优先。强制映射是控制台/ API 覆盖。 Capgo 会在最后一次覆盖写入 90 天后将其移除。参见 Console 和 API 的覆盖配置会过期.
  2. 云端覆盖(Dashboard 或公共 API):在 Dashboard 或通过公共 API 更改设备通道时,会写入与该设备 ID 绑定的覆盖。重新安装应用不会 不会 清除它;删除覆盖才会。同样适用 90 天保留期。
  3. 插件 setChannel() (本地):在当前插件版本中, setChannel() 在后端验证后将通道存储在设备上。这不是 Dashboard 覆盖。在 Android 和 iOS 上,使用 8.51.0 及更高版本的 updater 时, persistDefaultChannelOnReinstall 默认为 true,因此只有当操作系统恢复应用数据时,该选择才能在重装后保留,并且 persistDefaultChannelOnReinstall 保持 true. 调用 unsetChannel() 以显式清除本地选择。
  4. Capacitor 配置 defaultChannel (测试构建默认值):对于内部 / beta / 测试构建,你可以设置 defaultChannel (旧版 key channel)在 capacitor.config.* 让测试设备从预发布频道启动(例如 beta, pr-123)。如果未设置,设备将使用云端默认值。生产构建通常不设置此项。
  5. 云端默认频道(约 99% 用户的主要策略):几乎所有真实用户都会进入的主生产频道。任何没有强制指定、没有覆盖、没有本地 setChannel(),且无需配置 defaultChannel 将使用此项。更改后可在数秒内为所有人推送(或回滚),无需新的二进制文件。

为什么 云端默认值 是主要路径:

  • 即时发布或回滚,无需重新构建或重新发布原生二进制文件。
  • 在一个地方统一管理 iOS、Android 和 Electron 的行为。
  • 更安全:在切换默认设置前,你可以确认 bundle 是否存在以及设置是否正确。
  • 变更可审计(团队成员可以在 UI / logs 中查看谁改了什么)。 设计原则:上层(强制 / 覆盖 / 配置)是 例外情况 (调试单个用户、QA 切换、测试 build 默认值)。普通用户会使用云端默认值。

更改 云端默认值 通道影响 新 满足以下条件的常规设备:

  • 未被强制指定
  • 还没有云端覆盖
  • 没有应用层级的 defaultChannel 定义

如果测试 build 发布时带有 defaultChannel: 'beta' 之后你把云端默认值改为 production,从 开始运行的设备 beta 通过配置会保持在该状态,直到更高优先级的分配生效,或者直到你发布不带 的二进制文件 defaultChannel。删除强制、云端覆盖或本地 setChannel() 分配并不会移除配置值;该回退值会一直保留,直到新的二进制文件发布。

除非你执行以下操作,否则设备将保持在当前 channel:

  • 强制它们切换到另一个 channel(通过控制台或 Public API)。
  • 在 dashboard 或 Public API 中更改云端覆盖。
  • 调用 setChannel() (当前插件版本下的本地分配)。
  • 移除或归档它们所在的 channel(之后在下次检查时,它们将再次按优先级回退)。
  • 等待控制台/API 覆盖在 90 天后过期。
  • 调用 unsetChannel() 以清除本地 setChannel() 分配。这不会移除控制台/ API 覆盖项或应用配置的 defaultChannel;常规优先级规则重新生效。
  • 重新安装应用可清除本地分配,适用于旧版 updater 或应用数据未恢复的情况。在 updater 8.51.0 及更高版本的 Android 和 iOS 上, persistDefaultChannelOnReinstall 默认为 true,因此只要该选项保持开启,恢复的应用数据即可保留本地选择 true。Console/API 覆盖设置不受影响。

如果某个 channel 在某个平台上被禁用(参见 iOS / Android / Electron 开关),而它原本会被选中,则选择会跳过它并回退到下一条规则。

注意:设置 defaultChannel 意味着更改它需要新的 binary;请仅在测试/QA 中刻意使用,不要用于常规生产控制。

capacitor.config.ts
// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
plugins: {
CapacitorUpdater: {
defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
// legacy key: channel
},
},
};
export default config;

如果之后将 dashboard 默认值更改为 production,已处于其他 channel 的设备(通过 config、override 或 force)不会自动切换;只有新设备(或清除 override/force 的设备)才会应用该设置。


首先,让我们看看 channels 页面。您可以通过 点击你的应用 然后 点击 channels 标签页.

channel 列表

如你所见,右下角有一个加号按钮。(1 图中)点击它会打开一个模态框,你可以在其中创建新 channel。

新 channel

然后,在你点击 Add 列表中应会出现一个新的 channel。

channel 创建后

“配置错误”是什么意思?

标题为“配置有误是什么意思?”的部分

有时 channel 的配置无效。在这种情况下,你会看到一个醒目的警告,并且 Misconfigured 列将显示 Yes 针对一个或多个 channel。 你可以了解更多。 这里

要从 Web 应用删除 Channel,请打开 通道 你应用的标签页,并找到 Channel 行。在 操作 列中,点击垃圾桶图标,然后点击 删除 在确认对话框中。

显示删除垃圾桶图标的 Channel 行操作列

如果看不到垃圾桶图标,说明你的账号没有该应用的 channel.delete 权限。请联系组织或应用管理员授予可删除 Channel 的角色,或使用有权限的 API 密钥删除该 Channel:

终端窗口
npx @capgo/cli@latest channel delete <channel-name> <app-id>

绑定到组织和 App 的 应用预览 key 能以原子操作仅删除其创建的非公开预览 channel 和 bundle channel delete <preview-channel> <app-id> --delete-bundle。它无法更改或删除现有的 default/main channel、其他预览密钥的 channel 或其他密钥的 bundle。请参阅 API 密钥 了解最小权限配置。

点击 channel 名称打开 channel 页面。这是一个带标签页的完整页面,不是弹窗。

Channel 设置

Channel 标签页

“Channel tabs” 章节
  • 仪表盘:当前 bundle 的采用率及该 channel 的安装统计数据。
  • 信息:下方列出的 Channel 设置,以及渐进式发布和 Test Update API。
  • 设备:仅显示通过 Console 或 Public API 创建的强制映射。它不会列出当前在该 channel 上的所有设备,也不会列出使用过 setChannel()。请参阅 Console 和 API 的覆盖配置会过期.
  • 历史记录:该 channel 的设置和 bundle 变更记录。
  • 预览:在浏览器和原生端预览关联的 bundle。启用 bundle 预览,请在 App 信息 首先。

保持在 信息 标签页。设置按以下顺序显示:

首先, 默认下载通道 是状态徽章,不是开关。 活跃 表示该通道是新设备的云端默认通道。点击 在 App 设置中管理 以更改 App 信息上的默认设置。如需设置平台特定的默认值(iOS、Android 和 Electron 各一个),请参阅同一章节。

第二项是 IOS 设置。如果此项为 false,iOS 设备将无法从此通道下载更新。

第三项是 Android 设置。如果此项为 false,Android 设备将无法从此通道下载更新。

第四项是 Electron 设置。如果此项为 false,Electron 应用将无法从此通道下载更新。

第五是 Disable auto downgrade under native 设置。如果此项为 true,则无法从原生版本降级。这意味着如果你已经将某个 1.2.0 版本上传到 App Store 或 Play Store,并尝试将 channel 版本设置为 1.1.0 ,那么更新(降级)将会失败。

第六项是 Disable auto update。此设置比较复杂,你可以进一步了解 这里

第七项是 Download format 设置。它决定设备是下载完整 zip 包、仅下载变更的 delta 文件,还是采用两者中的最优方式。参见 下载格式.

第八项是 Allow development build。如果此项为 true,则允许开发构建从该 channel 下载更新。否则,任何将 prod 设置为 false 的更新请求都将被拒绝。这主要用于测试。

第九项是 Allow production build。如果此项为 false,生产环境(应用商店)构建将不会从此渠道接收更新。对于面向真实用户的渠道,请保持此项开启。

第十项是 Allow Emulators。如果此项为 false,Capgo 将拒绝来自模拟器的任何更新请求。这主要用于测试目的。

第十一项是 Allow physical devices。如果此项为 false,Capgo 将拒绝来自真实手机和平板电脑的更新请求。对于生产环境渠道,请保持此项开启。

第十二项是 Allow devices to self dissociate/associate。如果此项为 true,则 setChannel 方法将在 Android 和 iOS 上可用。如果此项设为 false 且你尝试调用 setChannel 使用此通道时,调用将会失败。

在 信息 选项卡底部,展开 测试更新 API。Capgo 会显示一条针对 /updates 该频道下示例设备的 curl 命令。

由于缓存,更改可能需要长达 60 秒才会在 API 中显示。如果该频道无法测试,控制台会警告你:该频道至少需要一个平台(iOS 或 Android)、生产构建、真机,并且要么是默认下载频道,要么允许设备自行分配。

更改关联的 bundle 后,控制台可能会要求你 发送更新通知。这会将一个静默推送加入队列,让该 Channel 上的设备立即检查新的 bundle。请先在应用的 Notifications 标签页中配置 Android 和 iOS 的推送凭据。

Console 和 API 的覆盖配置会过期

标题为“Console 和 API 覆盖设置过期”的章节

强制映射以及 Dashboard/Public API Channel 覆盖设置将被移除 90 天 在最后一次覆盖设置写入后。设备最后一次签到不会重置这个计时。对于能在此清理后保留的分配,请设置 defaultChannel 在您的 Capacitor 配置中(重装后仍保留,更改需新的二进制文件)或调用 setChannel() 在 Android 或 iOS 应用中,使用 @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+,或 8.0.0+ 针对您插件的主版本。这些版本会将分配存储在本地,从而避免 90 天的清理。早期版本会写入后端覆盖设置,同样受此清理影响。在 Android 和 iOS 上,使用 8.51.0 及更高版本的 updater 时, persistDefaultChannelOnReinstall 默认为 true,因此只有当操作系统恢复应用数据时,本地选择才能在重装后保留,并且 persistDefaultChannelOnReinstall 保持 true。使用 persistDefaultChannelOnReinstall: false 可能会清除该本地选择,即使应用数据已恢复。请使用 unsetChannel() 显式清除该本地选择。

Capgo 频道的“设备”选项卡,显示覆盖保留期弹窗:控制台覆盖在 90 天后过期
频道“设备”选项卡上的覆盖保留期。当您将设备 ID 强制绑定到该频道时,也会显示相同的提示。

这与 设备清单保留不同。库存管理会移除 90 天内未连接 Capgo 的设备。覆盖清理则会移除映射关系,即使设备仍处于活跃状态。详细信息: Console 和 API 覆盖将在 90 天后过期.

打开一个 channel,并停留在 信息 选项卡。 下载格式 位于设置列表中的“禁用自动更新”下方。

Capgo channel 上的下载格式下拉菜单,显示 Zip + delta、Full zip only、Delta only、Full zip from store build only 以及 Delta from store build only
channel 信息选项卡上的下载格式。新 channel 默认使用 Zip + delta。

此设置决定当该 channel 下的设备检查更新时,Capgo 发送什么内容。保持 Zip + 增量更新 除非你需要强制使用某种特定格式。

控制台中的标签CLI / API 值设备下载内容
Zip + delta(默认)all每个设备都会获得其支持的最佳包。使用支持 Delta 的插件版本的设备,在 bundle 包含 delta 文件时只下载变更的 delta 文件。只有使用不支持 Delta 的旧版插件的设备,或上传时不含 delta 文件的 bundle,才会回退到完整 zip。
仅 Full zipzip即使存在 delta 文件,每台设备也会下载完整的 bundle zip。
仅 Deltadelta仅下载变更的 delta 文件。使用不支持 Delta 的旧版插件的设备,在 bundle 包含完整 zip 时仍会收到完整 zip。
仅 Store Build 版本用 Full zipzip_from_builtin设备仍处于 Store Build 时仅使用 Full zip。首次 live update 后,Capgo 会再次提供 zip + delta。
仅 Store Build 版本用 Deltadelta_from_builtin设备仍处于 Store Build 时仅使用 Delta。首次 live update 后,Capgo 会再次提供 zip + delta。

使用 Zip + 增量更新,看到一些完整的 zip 下载是正常的。它们来自仍运行旧版原生构建且插件版本不支持 Delta(低于 5.10.0, 6.25.0,或 7.0.35 其主要版本)的设备。参见 增量更新.

本指南中介绍的 商店构建 是 App Store 或 Play Store 二进制文件中包含的 Web 资源,在任何 Capgo 更新之前。使用 from store build only 模式,当从商店构建进行的首次更新仅应为完整 zip 或仅 delta,而后续更新可使用两者时。

Capgo 不会将仅 zip 通道与仅 delta 捆绑包配对,反之亦然。控制台、CLI 以及 通道 API 拒绝保存,并提示你上传缺失的包或切换模式。

你也可以从 CLI 设置相同的值。通道必须已存在:

终端窗口
npx @capgo/cli@latest channel set production com.example.app --update-package zip

有效值: all, zip, delta, zip_from_builtin, delta_from_builtin.

通道 信息 选项卡包含一个 渐进式发布 包含以下内容的部分 发布目标 以及 稳定回退版本, 更改发布目标, 应用百分比,以及操作 完成发布, 回滚发布, 启用发布, 禁用发布, 暂停发布,以及 恢复发布.

Capgo channel 中的渐进式发布控制
渐进式发布控制项位于频道信息标签页顶部。

读取 渐进式发布 启用前。该指南涵盖上传路由(自动(推荐) / 发布目标 / 替换稳定版; CLI --stable / API target: "stable" 以覆盖),该 此频道使用渐进式发布 bundle 链接对话框,以及安全的工作流 Observe 以及 日志洞察.

继续探索 Channels

“从 Channels 继续”部分

如果你正在使用 通道 要规划 Channel 路由和分阶段发布,请将其与 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, Beta 测试解决方案 有关 Beta 测试解决方案的产品工作流, 版本定向解决方案 有关版本定向解决方案的产品工作流,以及 Capgo 环境最佳实践:使用一个 Mobile App ID 进行 Staging 有关 Capgo 环境最佳实践:使用一个 Mobile App ID 进行 Staging 的实际场景。