渠道

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

频道不提供保密性

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

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

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

1. 强制设备映射（控制台） – 手动将特定设备 ID 固定到频道。用于紧急调试或在单个真实用户下进行控制测试。
2. Cloud override (per‑device) via Dashboard or 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__更改），设备需要等待数据复制（最多 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.

因为 setChannel() 是本地的，所以它 不 在Capgo控制台中创建一个设备Override条目。设备Override UI只显示从控制台或公共API创建的Override。

注意： 即使一个通道在本地设置后被禁止，后端仍会在更新检查期间验证该通道，因此安全性得到维护。

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

4. Capacitor配置 defaultChannel （测试构建默认值） – 如果存在于 capacitor.config.* 如果没有force/override/local channel，应用程序将在此通道启动（例如， beta, qa, pr-123。适用于TestFlight / 内部构建，以便测试者自动进入预发布通道。生产构建通常不设置此选项。
5. Cloud Default Channel (主要路径 ~99% 的用户) – 如果在控制台中标记了默认通道，所有正常用户（无force，无控制台/API 强制，无插件本地通道，无配置defaultChannel）将连接到此处。修改它即可立即推出或回滚—无需新二进制文件。如果您有平台特定的默认值（例如，一个iOS-only，一个Android-only，一个Electron-only），每个设备将连接到匹配其平台的默认值。未设置Cloud Default允许；在这种情况下，设备必须匹配步骤1-4才能接收更新。

最佳实践：

• 将1-4视为异常/测试层次；当您设置Cloud Default时，真实用户应该流入它。如果您选择不设置一个，请务必明确用户如何连接（通常通过 defaultChannel 在配置或设备级别的覆盖中）。
• 仅在 defaultChannel 中配置，仅在您明确向测试者分发的二进制文件中。未设置它将使生产逻辑在控制台中集中。
• 仅在生产中 setChannel() 使用sparingly—主要用于QA或目标诊断。

如果一个通道在平台上（iOS/Android/Electron切换）被禁用，选择过程将跳过它并继续下一项。

概要：Force > Dashboard/API Override > Plugin setChannel() 本地频道 > Config defaultChannel > Cloud Default.

默认频道行为

设置云端默认值是可选的，但通常作为新设备的通用路径。没有一个，仅有匹配强制映射、覆盖或__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 ios-production – android-production With 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 在非生产通道上启动的二进制文件，即使云默认值不同。

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

设置通道

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

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

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

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

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

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

打开您的 capacitor.config.ts (或 capacitor.config.json)文件。 在 plugins 部分中， defaultChannel 可选 设置 测试构建

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.
    },
  },
};

优先考虑省略它，以便设备使用 Cloud Default，除非显式覆盖。 npx cap sync 复制到剪贴板

构建您的Web应用并运行

Channel selection order: Force > Dashboard/API device override > Plugin setChannel() local channel > 配置 defaultChannel > 云端默认.

仅在测试/内部构建中使用; 在生产环境中请勿包含，以便用户遵循云端默认设置（如果已设置）而不是重复在本地配置中设置路由. 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 渐进式发布

渠道可以保持稳定的包，同时逐渐向粘性设备群暴露一个单独的发布目标。您可以暂停、恢复、推动、回滚和配置自动失败响应，而不需要为所有人切换渠道。请参阅

了解交付模型、仪表板工作流、__CAPGO_KEEP_0__字段和__CAPGO_KEEP_1__命令。 渐进式发布 for the delivery model, dashboard workflow, API fields, and CLI commands.

禁用自动更新策略

使用此选项来限制通道自动分发的更新类型。选项：

• 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 targetLanguage":"Simplified Chinese" 1.0.0-beta.1 -> 1.0.0-beta.2 protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"] 1.0.0+build.1 -> 1.0.0+build.2 texts":["保持不变。例如：","允许，","允许，","被阻止。", 1.0.0 -> 1.0.1 metadata: 每个捆绑包都需要要求最小的更新版本元数据。通过__CAPGO_KEEP_0__配置","或","。如果缺失，通道将被标记为不配置，更新将被拒绝，直到设置。",
• metadata: Require a minimum update version metadata on each bundle. Configure via CLI using --min-update-version , --auto-min-update-version更多详细信息和示例，请参见 /docs/__CAPGO_KEEP_0__/commands/#disable-updates-strategy.
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__.

__CAPGO_KEEP_0__ version_build__CAPGO_KEEP_0__ version_name.

cli

示例 (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

使用 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
});

How setChannel() Works (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() 从插件	即刻	仅设备 (本地)	否	用户在应用内切换频道
设备控制台	至多 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，都包含相同的功能）。请参见 插件安装 了解版本标签。

将捆绑包分配给频道

要部署实时更新，您需要上传一个新的 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 Tester semantic versioning with Capgo’s Semver Tester 预发布标识符 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

这是一个推荐的方法，但不是严格要求的。关键是找到一个清晰地表达您的构建之间关系并与团队的开发过程一致的版本控制方案。 回滚一个在线更新 标题：回滚一个在线更新

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

找到您要恢复的构建并点击冠军图标

1. __CAPGO_KEEP_0__
2. __CAPGO_KEEP_1__
3. 确认操作

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

自动化部署

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

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

最少权限PR预览

使用 App 预览 API key when CI needs one temporary channel per pull request but must not manage existing main/default channels. The key remains bound to the owning organization and selected app; it simply has no organization-wide role. Each non-public preview channel it creates receives its own automatic, channel-scoped lifecycle permission.

1. 请组织管理员创建一个仅限预览应用的安全API密钥并选择 App 预览. 查看 API密钥.
2. 使用一个唯一的非公开渠道，如 pr-123. 不要传递 --default, --self-assign, --delete-linked-bundle-on-upload.
3. 滚动选项或

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel 创建一个缺失的频道，上传包并在一个流程中推广它。清理是原子性的并且拥有者检查：该键只能删除它创建的频道和其链接但未共享的包。它不能改变、推广或删除一个现有的主/默认频道、另一个预览键的频道或另一个键的包。

如果审阅者需要一个二维码code或预览URL，管理员必须为应用程序启用预览一次：

npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

一个应用预览键无法启用预览，因为它没有应用设置的权限。在GitHub Actions中，运行带有机密的预览作业在 pull_request，不 pull_request_target，并将其限制为同仓库的PRs中 github.event.pull_request.head.repo.full_name == github.repository.

部署到设备

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

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

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

高级频道使用：用户分段

频道不仅可以用于开发阶段，还可以用于用户分段。它是一种强大的工具，支持以下功能：

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

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

继续从渠道

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