频道

Live Update 通道指向您的应用程序的特定 JS 构建包，任何配置为监听该通道的设备都会共享该通道。您 在您的应用程序中安装 Capgo Live Updates SDK ，任何配置为该通道的原生二进制文件将在应用程序启动时检查可用更新。您可以随时更改通道指向的构建，并且也可以回滚到以前的构建版本。

通道不提供保密性

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

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

当设备检查更新时，Capgo 根据以下顺序（优先级最高）决定使用哪个频道：

1. 强制设备映射（控制台） – 手动将特定设备 ID 附着到频道。用于紧急调试或受控测试。
2. Cloudflare 覆盖 (按设备) 通过控制台或 API – 当您在控制台或 API 中更改设备的频道时创建。用于 QA 用户在特性 / PR 频道之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目会清除它。

使用 setChannel() 实现即时频道切换

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始 （取决于您的主版本）， setChannel() 它与后端联系， 验证 该频道是否允许（检查是否为该频道启用自我赋值），然后存储频道 本地设备上 作为 defaultChannel. 这意味着新的频道立即生效 不需要等待数据复制 之前

将频道覆盖保存到后端数据库（如控制台或__CAPGO_KEEP_0__更改），设备需要等待数据复制（最多2分钟）才能识别新的频道。新行为只从后端读取（验证）并在本地存储，从而使频道切换立即生效 setChannel() saved the channel override to the backend database (like Dashboard or API changes), and devices had to wait for data replication (up to 2 minutes) before the new channel was recognized. The new behavior only reads from the backend (for validation) and stores locally, making channel switches instant.

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

通过控制台或__CAPGO_KEEP_0__进行的频道更改仍然存在2分钟的复制延迟，所有边缘服务器才会反映更改。要实现立即频道切换，请 从您的应用API中使用—它与后端验证，然后在本地设置频道以立即生效。 setChannel() from your app code—it validates with the backend, then sets the channel locally for immediate effect.

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

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

• 在配置或设备级别的覆盖中）。 defaultChannel 仅配置
• 在您明确向测试者分发的二进制文件中配置。未设置它将保留生产逻辑在控制台中。 defaultChannel Cloudflare
• 在生产环境中，尽量少用—主要用于QA或针对性的诊断。 setChannel() 如果一个通道在平台（iOS/Android/Electron切换）上被禁用，选择过程将跳过它并继续下一项。

强制 > 覆盖 > 配置

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

标题：设备通道行为

单个默认值（最常见） defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

• 平台特定的默认值 Platform-specific defaults
• Platform-specific defaults – 如果您根据平台分隔通道（例如， ios-production 仅 iOS 启用， android-production 仅 Android 启用，和 electron-production 仅 Electron 启用），则将每个平台的默认值标记为其平台的默认值。 iOS 设备将前往 iOS 默认值，Android 设备将前往 Android 默认值，Electron 应用将前往 Electron 默认值。

请记住， defaultChannel 云端默认值和 capacitor.config.* both occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your Capacitor config—leave defaultChannel 同一决策层上占据。 如果您设置了云端默认值，您不需要在 __CAPGO_KEEP_0__ 配置中重复该值—在生产构建中留 defaultChannel 空。 预留

用于您故意将测试或 QA 的二进制文件发送给测试人员或 QA 时，希望它们在非生产通道上启动，即使云端默认值与之不同。

您可以在控制台中随时更改默认值。当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时将遵循正常的优先级规则。

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

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

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

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

在您的应用程序中配置频道

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

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

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.

• Default channel: Optionally mark the channel or platform-specific channels that new devices attach to. See “Default Channel Behavior” for routing scenarios.
• 平台过滤器：启用或禁用向 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: 根据 语义版本兼容性.

Learn more details and examples in Disable updates strategy at /docs/cli/commands/#disable-updates-strategy.

Learn more details and examples in Disable updates strategy at /docs/CLI/commands/#disable-updates-strategy。

# 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

使用 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() 被称为：

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

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

安全注意事项： 即使一个频道的权限在本地设置后发生变化（例如，自我赋权被禁用），后端仍会在更新检查期间验证频道，以确保安全性得到维护。

频道变更方法比较：

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

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

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

分配一个包到一个频道

为了部署一个实时更新，您需要上传一个新的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.

Section titled “包版本和频道”

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的Semver Tester 并为渠道特定构建使用预发布标识符。例如，一个beta版本可能被版本化为 1.2.3-beta.1.

这种方法有几个好处：

• 它清晰地表明了构建之间的关系。 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是推荐方法，但不是严格要求的。关键是找到一个清晰地表达您构建之间关系的版本控制方案，并与您的团队的开发过程保持一致。 回滚一个正在运行的更新 标题：回滚一个正在运行的更新

__CAPGO_KEEP_0__

如果您部署的实时更新引入了错误或需要回滚，

1. 从仪表板的“频道”部分：
2. 点击您要回滚的频道名称
3. 回滚构建

确认操作

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

For more advanced workflows, you can automate your live update deployments as part of your CI/CD pipeline. By integrating Capgo into your build process, you can automatically upload new bundles and assign them to channels whenever you push to certain branches or create new releases.

对于更复杂的工作流程，您可以将实时更新的发布自动化为您的CI/CD管道的一部分。通过将__CAPGO_KEEP_0__集成到您的构建过程中，您可以自动上传新包并将其分配到频道，任何时候您推送特定分支或创建新发布时。 查看 docs to learn more about automating Capgo live updates.

在设备上部署

了解了通道后，你就可以开始在真实设备上部署实时更新了。基本流程是：

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

对于更详细的教程，请参阅 实时更新部署 指南。快乐更新!

高级通道使用：用户分段

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

• 不同用户等级的功能标志
• A/B测试
• 逐步功能发布
• 测试计划

了解如何在我们的指南中实现这些高级用例： 如何根据计划和频道对用户进行分段，用于功能标志和A/B测试.

继续使用频道

如果您正在使用 频道 来规划频道路由和阶段发布，连接它 频道 关于频道的实现细节 频道 关于频道的实现细节 Beta 测试解决方案 关于 Beta 测试解决方案的产品工作流程 版本目标解决方案 关于版本目标解决方案的产品工作流程 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期 关于 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期的实际背景