通道

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

刚开始使用 channels？观看三个简短的频道演示视频了解默认路由、设备自行分配和控制台覆盖的实际效果。

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

Capgo 如何选择频道（优先级）

当设备向 Capgo 请求更新时，会按以下顺序决定使用哪个频道（优先级从高到低）：

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

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

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

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

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

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

除非您执行以下操作，否则设备将保持在当前 channel：

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

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

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

Capacitor 配置示例

// 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 标签页.

创建频道

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

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

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

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

删除频道

若要从 Web App 中删除 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 标签页

Dashboard：当前 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，则生产环境（应用商店）版本将无法通过此 channel 获取更新。对于面向真实用户的 channel，请保持开启状态。

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

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

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

测试更新 API

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

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

发送更新通知

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

Console 和 API 的覆盖配置会过期

强制映射以及 Dashboard/Public API channel 覆盖配置将被移除 90 天 在最后一次写入覆盖配置后执行。设备的最后一次 check-in 不会重置该计时器。若要设置一个能避开清理机制的 assignment，请在 defaultChannel 你的 Capacitor 配置中设置（即使重新安装也有效，但更改需重新构建 binary）或调用 setChannel() 从 Android 或 iOS 应用中调用，并使用 @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+，或 8.0.0+ 来指定你插件的主版本号。这些版本会将 assignment 存储在本地，从而避开 90 天清理机制。早期版本会写入后端覆盖配置，同样受此清理机制影响。在 Android 和 iOS 上使用 8.51.0 及更高版本的 updater 时， persistDefaultChannelOnReinstall 默认为 true，因此只有在操作系统恢复应用数据时，本地选择才能在重新安装后保留，并且 persistDefaultChannelOnReinstall 保持 true。使用 persistDefaultChannelOnReinstall: false 进行重新安装可能会清除该本地选择，即使应用数据已恢复。请使用 unsetChannel() 来显式清除该本地选择。

Capgo channel Devices 标签页显示 Override retention 弹出框：console overrides 在 90 天后过期 — channel Devices 标签页上的 Override retention。当你向 channel 强制指定 device ID 时，也会出现相同的提示。

这与设备清单保留时长是分开的。Inventory 会移除 90 天未连接到 Capgo 的设备。Override cleanup 即使在设备仍处于活跃状态时也会移除映射关系。详情如下： Console 和 API 覆盖将在 90 天后过期.

下载格式

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

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

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

使用 Zip + 增量更新，看到一些全量 zip 下载是正常现象。这通常是因为设备仍在使用旧版本的 Native Build，且其插件版本尚不支持 Delta（低于 5.10.0, 6.25.0，或 7.0.35 其主版本）。请参阅增量更新.

本指南中介绍的 商店构建版本 是指在进行任何 Capgo 更新之前，随 App Store 或 Play Store 二进制文件一同发布的 Web 资源。使用 from store build only 模式可以指定在商店构建版本之后的首次更新仅限全量 zip 或仅限 delta，而后续更新则可以两者兼用。

Capgo 不会将仅限 zip 的 Channel 与仅限 delta 的 bundle 进行配对，反之亦然。控制台、CLI 以及频道 API 拒绝保存，并提示你上传缺失的 package 或切换模式。

你可以在 CLI 中设置相同的值。该 channel 必须已存在：

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

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

渐进式发布

channel 信息标签页包含一个 渐进式发布 带有以下内容的章节 发布目标 以及 稳定回退版本, 更改发布目标, 应用百分比，以及操作 完成发布, 回滚发布, 启用发布, 禁用发布, 暂停发布，以及 恢复发布.

读取渐进式发布在启用其中之一之前。该指南涵盖了上传路由（自动（推荐） / 发布目标 / 替换稳定版; CLI --stable / API target: "stable" 以进行覆盖）， 此频道使用渐进式发布 bundle-link dialog, and a safe workflow with Observe 以及日志洞察.

继续探索 Channels

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