渠道

当您 在应用程序中安装 Capgo Live Updates SDK 时，任何配置为监听该频道的设备都会检查可用更新。您可以随时更改频道指向的构建，并且也可以回滚到之前的构建版本。

频道不提供保密性

频道控制更新的资格，而不是构建的保密性。即使频道是私有的或自我赋值被禁用，任何未加密的构建上传到 Capgo 也应该被视为一个公共资产，交付给客户端。加密保护了更新的传递路径和真实性，但仍然可以通过逆向工程从分发的应用程序中逆向工程出已发货的构建，因为客户端的公共密钥是其中的一部分。请参阅 Live Update 加密 了解更多详细信息。

设备如何选择频道（优先顺序）

When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):

1. Forced device mapping (Dashboard) – 手动将特定设备 ID 固定到一个频道中。用于紧急调试或受控测试。
2. Cloud override (per-device) via Dashboard or API – 当您在控制台或 API 中更改设备的频道时创建。用于 QA 用户在特征 / PR 频道之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目会清除。

Instant Channel Switching with setChannel()

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始 (取决于您的主版本) setChannel() 工作方式不同：它会联系后端 验证 该频道是否允许（检查是否为该频道启用自我赋值），然后存储频道 在设备上 而 defaultChannel. 这意味着新的频道立即生效 下一次更新检查时 不需要等待复制

之前 setChannel() 将频道覆盖保存到后端数据库（如控制台或API更改），设备需要等待数据复制（最多2分钟）才能识别新的频道。新行为只从后端读取（验证）并存储本地，频道切换立即生效

注意： 即使在设备上设置的频道被禁止后，后端仍会在更新检查期间验证频道，因此安全性得到维护

重要： 通过控制台或API进行的频道更改仍然存在2分钟的复制延迟，所有边缘服务器才会反映更改。要实现即时频道切换，请 setChannel() 从您的应用程序code—它与后端验证，然后将频道设置为本地以立即生效

3. Capacitor 配置 defaultChannel (测试构建默认值) – 如果在 capacitor.config.* 中存在且没有强制/覆盖存在，应用程序将在此通道启动（例如，）。用于 TestFlight / 内部构建，以便测试者自动进入预发布通道。生产构建通常将其设置为未设置。 beta, qa, pr-123Cloud 默认通道（主要路径 ~99% 的用户)
4. – 如果在控制台中标记了默认通道，所有正常用户（无强制、无覆盖、无配置 defaultChannel）将附加到此。立即更改即可推出或回滚—无新二进制文件。如果您有平台特定的默认值（例如，iOS-only、Android-only、Electron-only），则每个设备将在匹配其平台的默认值。将云默认值设置为未设置是允许的；在这种情况下，设备必须匹配步骤 1–3 才能接收更新。 最佳实践：

将 1–3 视为异常/测试层；当您设置云默认值时，真实用户应该流入它。如果您选择不设置一个，请务必有意识地考虑用户如何附加（通常通过

• 在配置或设备级别的覆盖中）。 defaultChannel 仅配置
• 在您明确向测试者分发的二进制文件中。将其设置为未设置将保持生产逻辑在控制台中集中。 defaultChannel in binaries you explicitly ship to testers. Leaving it unset keeps production logic centralized in the dashboard.
• 在生产环境中，尽量少用—主要用于QA或针对性的诊断。 setChannel() 如果一个通道在平台（iOS/Android/Electron切换）被禁用时，选择过程会跳过它并继续下一项。

摘要：强制 > 覆盖 > 配置

> 云默认值。 defaultChannel 通道默认行为

标题：通道默认行为

在__CAPGO_KEEP_0__配置中 defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

• 单个默认值（最常见） – 如果一个通道同时启用了iOS、Android和Electron，会成为唯一的默认值；没有覆盖的设备都会附着在这里。
• 平台特定的默认值 – 如果您根据平台（例如 ios-production 仅有 iOS 启用 android-production 仅有 Android 启用 electron-production 仅有 Electron 启用

记住，云端默认值和 defaultChannel 在 capacitor.config.* 都占据同一决策层。如果您设置了云端默认值，那么您不需要在 Capacitor 配置中重复该值—在生产构建中留空。保留 defaultChannel 用于您故意将二进制文件发送给测试者或 QA 时，希望它们在非生产通道上启动，即使云端默认值不同。 defaultChannel 您可以在控制台中随时更改默认值。当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时遵循正常的优先级规则。

设置通道

标题：设置通道

在入门过程中，您创建第一个频道（大多数团队将其命名为“生产”），但没有任何内容被锁定—you 可以随时重命名或删除任何频道。要添加更多频道：

1. 前往 “频道”Capgo 的控制台
2. 点击 “新频道”按钮
3. 输入频道名称并点击 “创建”

频道名称可以是您喜欢的任何内容。一个常见的策略是将频道与您的开发阶段匹配，例如：

• Development - 在本地设备或模拟器上测试实时更新
• QA - QA 团队在更广泛发布之前验证更新
• Staging - 在生产环境中进行最终测试
• Production - 用户从应用商店接收的应用程序版本

配置频道

您创建了频道后，需要配置应用程序以监听适当的频道。在本例中，我们将使用 Development 频道.

打开你的 capacitor.config.ts (或 capacitor.config.json)文件。 在 plugins 部分，选择性地设置 defaultChannel 用于 测试构建 (内部/QA)。 对于生产构建，建议省略它，以便设备使用 Cloud 默认值，除非显式覆盖。

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 项目。如果你跳过这个同步步骤，native 项目将继续使用之前配置的频道。

注意

频道选择顺序：强制 > 覆盖（setChannel /控制台）> 配置 defaultChannel > Cloud Default.

仅在测试/内部构建中使用；在生产中排除它，以便用户遵循 Cloud Default（如果已设置）而不是在本机配置中重复路由。 defaultChannel 您仍然可以强制（固定）设备或稍后应用覆盖—这些立即优先于配置值。

频道名称区分大小写。

频道选项和策略

频道选项和策略

Channels have several options that control who can receive updates and how updates are delivered. The most important ones are below. You can configure these from the web app, the CLI, or the Public API.

• 频道选项和策略
• 平台过滤器：启用或禁用向 iOS, Android， Electron 设备每个渠道。
• 在本机下禁用自动降级：防止在设备的本机应用程序版本新于渠道的捆绑包时发送更新（例如，设备在 1.2.3 时，渠道有 1.2.2）。
• 允许开发构建：允许更新开发构建（用于测试）。
• 允许模拟器设备：允许更新模拟器/模拟器（用于测试）。
• 允许设备自我分配：让应用程序在运行时切换到此渠道使用 setChannel。如果禁用， setChannel 将失败此渠道。

禁用自动更新策略

使用此选项来限制哪种类型的更新将自动分发。选项：

• major: 阻止跨版本更新 (0.0.0 → 1.0.0)。仍允许修订和补丁更新。
• minor: 阻止跨修订更新 (例如，1.1.0 → 1.2.0) 和主要版本。仍允许修订更新。注意：不会阻止 0.1.0 → 1.1.0。
• patch: 极为严格。仅允许在同一主要和修订版本中增加补丁版本。示例：0.0.311 → 0.0.314 ✅，0.1.312 → 0.0.314 ❌，1.0.312 → 0.0.314 ❌。
• metadata: 要求每个捆绑包的最低更新版本元数据。通过 CLI 使用 --min-update-version 或 --auto-min-update-version配置。如果缺失，通道将标记为不正确，更新将被拒绝，直到设置。
• none: 根据 semver 兼容性允许所有更新。

了解更多详细信息和示例，请参见 /docs/cli/commands/#disable-updates-strategy。

示例 (CLI):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

使用 Your App 中的 setChannel()

The setChannel() 方法允许您的应用程序在运行时程序性切换通道。这在以下情况下特别有用：

• QA/调试菜单，测试人员可以在其中切换通道
• Beta 程序优选流
• 特征标志实现
• A/B 测试场景

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });

// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

setChannel() 如何工作（v5.34.0+ / v6.34.0+ / v7.34.0+ / v8.0.0+）

当 setChannel() __CAPGO_KEEP_0__

1. 后端验证 (只读): 发送一个请求到 Capgo 后端验证通道是否允许 (检查自赋值权限)
2. 本地存储更新: 如果验证通过，通道将保存到设备的本地存储中 defaultChannel
3. 即时效果: 下一次更新检查将立即使用新的通道 (无需等待复制)

为什么这很重要： 在旧版本中， setChannel() 将通道覆盖保存到后端数据库 (与控制台或 API 一样)。设备需要等待后端复制 (最多 2 分钟) 才能使通道更改生效。现在， setChannel() 只从后端读取 (用于验证) 并在本地存储，实现通道切换的即时效果。

安全说明： 即使在本地设置通道权限后 (例如，自赋值被禁用)，后端仍将在更新检查期间验证通道，确保安全性得到维护。

频道切换方法比较:

方法	生效时间	持久化位置	使用场景
setChannel() 从插件	即刻	仅设备端(本地)	用户在应用内触发的频道切换
设备控制台强制切换	至多2分钟	后端数据库	__CAPGO_KEEP_0__设备的特定设备的管理员触发的更改
API频道分配	最多2分钟	后端数据库	自动化的后端集成

在构建频道切换UI时，为了获得最佳用户体验，请始终使用插件的 setChannel() 方法。

仅限本地频道切换的最低版本： 5.34.0, 6.34.0, 7.34.0或 8.0.0 （取决于您的主要版本）。每个次要版本号对应的特性集在所有主要版本中相同（例如，X.34.0无论X是5、6、7还是8，都包含相同的功能。请参见 插件安装 了解版本标签。

为频道分配一个捆绑包

要部署一个实时更新，您需要上传一个新的 JS 捆绑包并将其分配到一个频道。您可以在一步中使用 Capgo CLI:

npx @capgo/cli@latest bundle upload --channel=Development

这将上传您的构建的 Web 资产并将新捆绑包设置为频道的活动构建。任何配置为监听该频道的应用程序将在下一次检查更新时接收更新。 Development 您还可以从 __CAPGO_KEEP_0__ 控制台的“捆绑包”部分分配构建。单击构建旁边的菜单图标并选择“分配到频道”以选择该构建的频道。

You can also assign builds to channels from the “Bundles” section of the Capgo dashboard. Click the menu icon next to a build and select “Assign to Channel” to choose the channel for that build.

频道分配捆绑包的部分

It’s important to note that bundles in Capgo are global to your app, not specific to individual channels. The same bundle can be assigned to multiple channels.

__CAPGO_KEEP_0__ semver __CAPGO_KEEP_0__ 1.2.3-beta.1.

使用特定渠道的构建的前期发布标识符。例如，beta版本可能以

• 这种方法有几个好处： 1.2.3-beta.1 它清晰地表明了构建之间的关系。 1.2.3.
• 显然是
• 它允许在渠道之间重用版本号，减少混淆。 1.2.3它使回滚路径清晰。您需要从 1.2.2 回滚到

您知道

• Development 这是上一个稳定版本。 1.2.3-dev.1, 1.2.3-dev.2以下是如何将您的捆绑包版本与典型的渠道设置对齐的示例：
• QA 频道: 1.2.3-qa.1, 1.2.3-qa.2等等。
• Staging 频道: 1.2.3-rc.1, 1.2.3-rc.2等等。
• Production 频道: 1.2.3, 1.2.4等等。

使用带有预发布标识符的semver是推荐的方法，但不是严格要求的。关键是找到一个版本方案，使其清晰地表明您的构建之间的关系，并与您的团队的开发过程保持一致。

回滚一个正在运行的更新

如果您部署了一个正在运行的更新，引入了一个错误或需要被撤销，请您可以轻松地回滚到一个之前的构建。从仪表盘的“频道”部分：

1. 点击您要回滚的频道的名称
2. 找到您要恢复的构建并点击冠军图标
3. 确认操作

所选的构建将立即成为该频道的活动构建。应用程序将在下一次检查更新时接收回滚的版本。

自动化部署

对于更高级的工作流程，您可以将实时更新部署作为您的CI/CD管道的一部分自动化。通过将Capgo集成到您的构建过程中，您可以自动上传新包并将其分配到频道，任何时候您推送到特定分支或创建新发布时。

查看 CI/CD集成 文档以了解更多关于自动Capgo实时更新的信息。

部署到设备

现在您了解了频道的概念，您就可以开始部署实时更新到真实设备了。基本流程是：

1. 在您的应用程序中安装 Capgo SDK
2. 配置应用程序以监听您的所需频道
3. 上传一个构建并将其分配到该频道
4. 启动应用程序并等待更新!

要了解更多详细步骤，请参阅 实时更新部署 指南。快乐更新!

高级频道使用：用户分段

频道不仅可以用于开发阶段，还可以用于用户分段，实现功能，如：

• 不同用户等级的功能标志
• A/B 测试
• 渐进式特性发布
• Beta 测试计划

了解如何在我们的指南中实现这些高级用例: 如何根据计划和渠道分段用户，用于特性标志和A/B测试.