通道

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

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

Channels control update eligibility, not bundle secrecy. Even if a channel is private or self-assignment is disabled, any unencrypted bundle uploaded to Capgo should still be treated as a public asset delivered to clients. Encryption protects the delivery path and authenticity of updates, but shipped bundles can still be reverse engineered from the distributed app with enough effort because the public key is part of the client. See 实时更新加密 for details.

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

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

1. 强制设备映射（控制台） – 手动将特定设备 ID 固定到频道中。用于紧急调试或在单个真实用户下进行受控测试。始终获胜。
2. Cloud 强制（每设备）通过控制台或 API – 当您在控制台或 API 中更改设备的频道时创建。用于 QA 用户在特征 / PR 频道之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目会清除它。
3. 插件 setChannel() 本地频道 – 当应用程序调用时创建 setChannel() 并且后端验证目标通道是否允许自我赋值。 选择的通道将在该设备上存储本地，立即生效，并不在设备覆盖UI中显示。

立即切换通道使用setChannel()

从插件版本5.34.0、6.34.0、7.34.0或8.0.0开始（取决于您的主版本）， 它与后端联系以 setChannel() 验证 该通道是否允许（检查是否为该通道启用自我赋值），然后将通道 在设备上存储本地 作为 。 这意味着新的通道立即生效 defaultChannel__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ targetLanguage":"简体中文","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["下次更新检查—等待复制完成。","之前，","将频道覆盖写入后端数据库（如控制台或__CAPGO_KEEP_0__更改），设备需要等待数据复制（最多2分钟）才能识别新频道。新行为只从后端读取（验证）并在本地存储，使频道切换立即生效。","因为","是本地的，所以它","不","创建一个设备覆盖项在__CAPGO_KEEP_0__控制台。设备覆盖UI只显示从控制台或公共__CAPGO_KEEP_1__创建的覆盖项。","注意：","即使频道在本地设置后被禁止，后端仍会在更新检查期间验证频道，因此安全性得到维护。","重要：","通过控制台或__CAPGO_KEEP_0__进行的频道更改仍然存在2分钟的复制延迟，所有边缘服务器才会反映更改。为了实现即时频道切换，请","从您的应用__CAPGO_KEEP_0__—它验证了后端，然后在本地设置频道以立即生效。"]

targetLanguage 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.

texts setChannel() 下次更新检查—等待复制完成。 之前 create a Device Override entry in the Capgo dashboard. The Device Override UI only shows overrides created from the dashboard or the Public API.

因为 是本地的，所以它

不 创建一个设备覆盖项在API控制台。设备覆盖UI只显示从控制台或公共__CAPGO_KEEP_1__创建的覆盖项。 setChannel() from your app code—it validates with the backend, then sets the channel locally for immediate effect.

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

最佳实践：

• 将 1–4 视为异常/测试层；当您设置云默认值时，真实用户应该流入它。如果您选择不设置一个，请务必对用户的连接方式有明确的认识（通常通过 defaultChannel 在配置或设备级别进行覆盖）。
• 仅配置 defaultChannel 在您明确向测试者分发的二进制文件中。将其设置为未设置将保持生产逻辑在控制台中集中。
• 建议在生产环境中谨慎使用—主要用于QA或针对性的诊断. setChannel() 如果一个通道在平台（iOS/Android/Electron切换）上被禁用，而它原本应该被选择，那么选择过程会跳过它继续下一项.

强制 > Dashboard/__CAPGO_KEEP_0__ Override > 插件

Summary: Force > Dashboard/API Override > Plugin setChannel() > 云默认. defaultChannel 默认通道行为

标题：默认通道行为

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

• – –
• targetLanguage":"Simplified Chinese" protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"] ios-production texts":["平台特定默认值","– 如果您根据平台（例如","仅 iOS","仅 Android","仅 Electron"），标记每个平台的默认值。 iOS 设备将前往 iOS 默认值，Android 设备将前往 Android 默认值，Electron 应用将前往 Electron 默认值。", android-production 请记住，云端默认值和"在"占据相同的决策层。如果您设置了云端默认值，您不需要在 __CAPGO_KEEP_0__ 配置中重复该值—在生产构建中留空。保留"用于您故意将二进制文件发送给测试者或 QA 时，希望它们在非生产通道上启动，即使云端默认值不同。", electron-production 您可以在控制台中随时更改默认值。当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时将遵循正常的优先级规则。",

设置通道"] defaultChannel Platform-specific defaults 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 with only iOS enabled, defaultChannel with only Android enabled, and

with only Electron enabled), mark each one as the default for its platform. iOS devices go to the iOS default, Android devices go to the Android default, and Electron apps go to the Electron default.

Remember that the cloud default and "in" occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your __CAPGO_KEEP_0__ config—leave empty for production builds. Reserve "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." You can change defaults at any time in the dashboard. When you swap a default, new devices obey the new routing immediately and existing devices follow the normal precedence rules the next time they check in." Setting up a Channel

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

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

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

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

在应用程序中配置频道

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

打开您的 capacitor.config.ts (或 capacitor.config.json)文件。在 plugins 部分中， optionally 设置 defaultChannel 用于 测试构建 (内部/ 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 项目。如果您跳过此同步步骤，则您的本机项目将继续使用它们之前配置的频道。

注意

频道选择顺序：强制 > Dashboard/API 设备覆盖 > 插件 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 将在此频道中失败。

禁用自动更新策略

Use this to restrict which kinds of updates the channel will automatically deliver. Options:

• major: 阻止目标包的主版本号高于设备本地基线的包（version_build). 例： 1.2.3 -> 2.0.0 是被阻止的； 1.2.3 -> 1.9.0 是允许的。
• minor: 阻止目标包的主或次版本号与 version_build不同。 例： 1.2.3 -> 1.3.0 是被阻止的； 1.2.3 -> 1.2.4 是允许的。
• 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 更新被阻止。
• 元数据：每个捆绑包都需要最低版本的更新元数据。通过 CLI 配置 --min-update-version 或 --auto-min-update-version如果缺失，通道将被标记为不配置，更新将被拒绝，直到设置。
• none: 根据 这些策略将通道的目标捆绑包与发送的本机基线进行比较，而不是下载的当前捆绑包.

Learn more details and examples in Disable updates strategy at /docs/__CAPGO_KEEP_0__/commands/#disable-updates-strategy。 version_build示例（__CAPGO_KEEP_0__）： version_name.

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()

这个 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+）

When setChannel() 被调用:

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

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

仪表板可见性： 使用插件设置的频道不会在Capgo UI中显示设备作为设备覆盖。只有从仪表板或公共API创建的频道 assignments 列在那里。使用仪表板或API时需要管理员可见的覆盖。

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

频道更改方法比较：

方法	效果时间	持久存储位置	在设备覆盖 UI 中显示	用例
setChannel() 从插件	即刻	__CAPGO_KEEP_0__	否	用户在应用内切换频道
设备控制台	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，都包含相同的特性）。请参见 插件安装 了解版本标签。

将包分配到频道

To deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the Capgo CLI:

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

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

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 Tester semantic versioning with Capgo’s Semver Tester 这种方法有几个好处： 1.2.3-beta.1.

它清晰地表明了构建之间的关系。

• Copy to clipboard 1.2.3-beta.1 __CAPGO_KEEP_0__ 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. 确认操作

The selected build will immediately become the active build for that channel again. Apps will receive the rolled back version the next time they check for an update.

自动化发布

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

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

发布到设备

现在您了解了通道的概念，准备好开始将实时更新发布到真实设备了。基本流程是：

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

详细的步骤请参见 实时更新部署 指南。更新愉快!

高级频道使用：用户分段

频道不仅可以用于开发阶段，还可以用于用户分段，支持以下功能：

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

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

继续从渠道

如果您正在使用 渠道 来规划渠道路由和分阶段发布，连接它与 渠道 查看渠道的实现细节在 渠道 查看渠道的实现细节在 Beta测试解决方案 为 Beta 测试解决方案中的产品工作流 版本目标解决方案 为版本目标解决方案中的产品工作流，并 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期 在 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期 中的实际上下文