频道切换指南：Capgo：如何在运行时切换更新频道

你是否曾经希望能够直接将更改发送给特定用户，让他们立即查看和反馈 - 而不必要求他们下载和安装新的测试版或谷歌商店版?

我有客户要求改进，我能够快速实施，但将结果传递给他们验证意味着需要将更新推送给所有用户（风险较高）或为客户创建一个单独的构建（对我们双方来说是一件麻烦事）。

开发者想要能够为不同用户组提供不同的更新，例如非技术人员、QA或整个用户基数在适当时。

没有办法让生产版切换到工作版本，收集反馈，然后返回生产版。

这就是 频道切换 使得

频道切换

Update channels are how Capgo targets updates to specific builds. Each build is associated with a channel, and that channel determines which updates it will receive.

了解更新频道 preview 更新频道是__CAPGO_KEEP_0__如何针对特定构建发送更新的方式。每个构建都与一个频道相关联，而该频道决定它将接收哪些更新。例如，你可以发布更新到一个频道而不影响用户在 production在过去，切换频道需要安装不同的本机构建或手动通过控制台更改设备分配。

Capgo频道允许您：

针对不同特性的用户群进行目标
通过分配用户到不同的频道来进行A/B测试
逐渐推出新功能
创建beta测试计划
使用单独用户来调试生产问题

如果您不熟悉更新频道，__CAPGO_KEEP_0__频道文档 Capgo channels documentation 什么是频道冲浪？

频道冲浪允许安装的应用程序从不同的更新流中拉取，而无需重新安装。安装的应用程序可以在运行时切换更新频道，并且它将继续从新选择的频道接收更新，直到应用程序被卸载或切换到另一个频道。

In the past, switching channels required installing a different native build or manually changing device assignments through the dashboard.

In实践中，这意味着产品负责人或QA可以切换到一个 production 例如 preview 频道，尝试最新的更改。当他们完成测试时，他们切换回 production 再次。无需重新安装或单独的预览构建。

在背后，频道切换的工作原理是让应用程序告诉更新客户端使用哪个频道。这个选择可以在运行时更改，并且直到它被清除或替换为止。

如何实现频道切换

在尝试频道切换之前，您的项目需要配置为Capgo Live Updates。要设置它，请遵循 Capgo快速入门指南.

频道切换所需的唯一设置是在Capgo控制台中为您要切换到的每个频道启用“允许设备自行关联”。 无需code更改或配置修改。

频道切换的核心是由一个API调用驱动的：

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

await CapacitorUpdater.setChannel({ channel: 'your-channel' });

这是设置用于查询Capgo更新的频道。了解更多关于 API 的设置.

即时频道切换 (v5.34.0+)

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始 (取决于您的主要版本) setChannel() 它的工作方式和速度都有所不同:

后端验证 (只读): 向 Capgo 后端发送请求，验证频道是否允许
本地存储更新: 如果验证通过，频道将保存到设备的本地存储
即时效果: 下一次更新检查将立即使用新频道

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

完整频道切换流程

为了提供更好的用户体验，您通常需要做的不仅仅是切换频道并等待下一次应用重启。一个常见的方法是立即检查更新、下载可用更新并重新加载应用，以便用户直接进入所选频道的更新。

典型的流程如下：

切换频道（setChannel)
检查更新（getLatest)
获取并应用更新（download, set 或者 next)
在这里，reload)

重新加载应用（

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

async function switchChannel(selectedChannel: string) {
  try {
    // 1. Set the updates channel (with optional auto-update trigger)
    await CapacitorUpdater.setChannel({
      channel: selectedChannel,
      triggerAutoUpdate: true // Immediately check for updates
    });

    console.log(`Switched to channel: ${selectedChannel}`);

    // If you want more control, handle the update manually:
    // const latest = await CapacitorUpdater.getLatest();
    // if (latest.url) {
    //   const bundle = await CapacitorUpdater.download({
    //     url: latest.url,
    //     version: latest.version
    //   });
    //   await CapacitorUpdater.set({ id: bundle.id });
    // }

  } catch (error) {
    console.error('Failed to switch channel:', error);
  }
}

// Switch to the beta channel
switchChannel('beta');

以下是完整的示例：

您可以按照自己喜欢的方式结构此流程。您可能会将这些步骤分散在多个交互中，也可能一次性完成。无论您如何结构流程，请确保考虑到失败。网络问题或无效的频道都可能阻止更新被应用。

只需这样做即可启用频道切换。 在使用 setChannel()之前，您必须在Capgo控制台中为该频道启用自我赋值：

前往频道 section in your Capgo dashboard
点击要管理的频道名称
允许设备自我关联 保存更改
在频道设置中启用自我赋值

就这样了。无需在您的应用程序中进行任何配置更改。

__CAPGO_KEEP_0__ defaultChannel 设置必备。只需在您希望用户可以切换到的频道上启用自我赋值即可。

如果此设置被禁用，任何尝试使用 setChannel() 使用此频道将会失败，并触发 channelPrivate 事件。

列出可用的频道

您可以获取自我赋值可用的频道列表:

const { channels } = await CapacitorUpdater.listChannels();

console.log('Available channels:', channels.map(c => c.name));
// Use this to build a channel selector UI

这只会返回自我赋值已启用的频道。

获取当前频道

检查设备当前被赋予的频道:

const { channel } = await CapacitorUpdater.getChannel();

console.log('Current channel:', channel);

恢复默认频道

要移除频道覆盖并返回到默认值:

await CapacitorUpdater.unsetChannel({});

这会将设备从任何特定赋予的频道中解除绑定，导致其回落到 defaultChannel 在您的配置文件或云端默认设置中。

如何测试频道切换

要看到频道切换的效果，您需要一个发布版本 - __CAPGO_KEEP_0__ 是专门为发布版本设计的。在调试版本中，应用通常从开发服务器加载 JavaScript，而不是正常的更新流程。 @capgo/capacitor-updater API is designed for release builds. In debug builds, the app typically loads JavaScript from a development server instead, which bypasses the normal update flow.

频道切换的唯一要求是启用

The only requirement for channel surfing is enabling 在每个允许切换的频道上启用 on each channel you want to allow switching to. No config changes are needed in your app.

创建测试版本

按照正常流程构建您的应用：

bun run build && npx cap sync

然后使用 Xcode 或 Android Studio 创建您的本机构建，或者使用您的 CI/CD pipeline。应用将从您的 Capgo 控制台中设置的云端默认频道开始。

将更新发布到不同的频道

安装应用程序后，发布到不同频道:

# Publish to preview channel
npx @capgo/cli@latest bundle upload --channel preview

# Publish to production channel
npx @capgo/cli@latest bundle upload --channel production

从那里，导航到应用程序中的频道浏览UI并触发频道切换。应用程序应从所选频道获取更新并重新加载到新更新。

构建频道切换器UI

频道浏览通常是您希望限制到特定用户组，而不是向所有使用应用程序的用户暴露的。例如，您可能有一个按钮可供认证员工切换到预览频道。

频道切换器的示例React组件:

import { useState, useEffect } from 'react';
import { CapacitorUpdater } from '@capgo/capacitor-updater';

export function ChannelSwitcher() {
  const [currentChannel, setCurrentChannel] = useState<string>('');
  const [availableChannels, setAvailableChannels] = useState<string[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    loadChannelInfo();
  }, []);

  async function loadChannelInfo() {
    const { channel } = await CapacitorUpdater.getChannel();
    setCurrentChannel(channel || 'default');

    const { channels } = await CapacitorUpdater.listChannels();
    setAvailableChannels(channels.map(c => c.name));
  }

  async function handleChannelSwitch(channel: string) {
    setIsLoading(true);
    try {
      await CapacitorUpdater.setChannel({
        channel,
        triggerAutoUpdate: true
      });
      setCurrentChannel(channel);
      // App will update in background or on next restart
    } catch (error) {
      console.error('Failed to switch channel:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div>
      <p>Current channel: {currentChannel}</p>
      <div>
        {availableChannels.map(channel => (
          <button
            key={channel}
            onClick={() => handleChannelSwitch(channel)}
            disabled={isLoading || channel === currentChannel}
          >
            Switch to {channel}
          </button>
        ))}
      </div>
    </div>
  );
}

OTA更新陷阱

这些并不是特定于频道浏览的，但在运行时切换频道时会变得显著。

运行时版本不匹配

Updates in Capgo are tied to native app versions. If the native version of an update doesn’t match the native version of the installed app, the update won’t be downloaded or applied. When channel surfing, this typically shows up as the app switching channels but no update being applied, even though one exists on that channel.

这通常意味着更新是从不同原生应用程序版本发布的。确保频道的捆绑包与设备上安装的原生版本兼容。

删除或撤销更新

如果应用程序已经下载了频道的更新，删除该更新从Capgo控制台中不一定会从设备上删除。删除只会停止未来下载。

发布一个已知的良好更新到同一频道是回滚一个坏更新的最可靠方法。这会在频道的历史中创建一个新的更新，客户端会将其视为最新版本并应用它而不是之前的版本。

Capgo 还提供了回滚机制，可以指示客户端重新应用之前的稳定更新或回退到构建中嵌入的更新。

数据迁移考虑

切换频道会改变应用程序运行的 JavaScript 包。如果您的应用程序依赖于迁移或数据形状，且这些迁移或形状在不同频道之间不兼容，频道切换可能会导致问题。

例如，如果一个 beta 更新应用了数据库迁移，生产版本可能无法理解新的 schema。开发人员应该确保更新在切换频道时仍然安全，或者在需要时限制切换到一方向。

频道切换为什么改善了移动迭代

频道切换尤其有用，当您需要在生产环境中快速查看更改时。

快速验证

想象一下，需要在广泛发布之前验证紧急修复。通过频道切换，修复可以被隔离到一小组指定用户中，他们可以在修复发布到生产环境之前对其进行审查。

利益相关者审查

A产品负责人或QA人员可以切换到另一个更新频道的已安装生产构建，验证修复或功能，然后切换回原来的频道一次他们完成后。

Streamlined Testing

使用场景

QA Testing

: QA团队可以在不同特性分支之间切换Beta Programs
: 用户可以选择加入早期访问的beta频道Stakeholder Review
: 产品负责人可以在发布前预览更改A/B Testing
: 将用户分配到不同频道进行实验Use Cases
调试: 将特定用户切换到调试频道以诊断问题

频道切换方法比较

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

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

限制访问

:频道浏览通常用于内部使用 - 不要将其暴露给所有用户最佳实践
处理错误: 在切换频道时始终优雅地处理错误
验证兼容性: 确保不同频道的更新与安装的原生版本兼容
频道文档: 对每个频道保持清晰的文档
监控使用: 跟踪设备在哪些频道上运行以便调试

资源

结论

频道切换变革了你如何迭代你的 Capacitor 应用。相比于将生产版本视为固定的终点，频道切换使其成为测试、验证和快速迭代的灵活工具。

通过最近插件版本中引入的即时频道切换功能，体验现在变得更加流畅 - 用户可以切换频道并立即从新频道接收更新，而无需等待任何时间。

无论你是在与利益相关者验证bug修复、运行beta测试还是调试特定用户的问题，频道切换都给你了灵活性来在正确的时间向正确的用户发送正确的更新。

继续阅读频道切换的 Capgo：如何在运行时切换更新频道

如果你正在使用 频道切换的 Capgo：如何在运行时切换更新频道 来规划频道路由和分阶段发布，连接它与频道上下文：Capgo发布频道功能名称。页面/区域：Capgo解决方案营销页面。角色：短的UI标签或导航项。见于：页面解决方案/白标签.astro。消息键 `solutions_white_label_visual_cell2_value` (解决方案白标签视觉单元2值)。频道切换的实现细节在频道中， Channels 频道 Channels Beta测试解决方案频道产品工作流程版本目标解决方案

Capgo频道切换