频道

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

Channels 不提供保密性

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

设备如何选择一个 channel（优先顺序）

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

1. 强制设备映射（控制台） – 手动将一个特定的设备 ID 映射到一个 channel。使用紧急调试或受控测试与一个真实用户。这个总是获胜。Capgo 在最后一次覆盖写入后 90 天后移除映射。请参见 控制台和 API 覆盖写入后 90 天.
2. Cloud override (per-device) via Dashboard or API – 当您在控制台或 API 中更改设备的 channel 时创建。使用 QA 用户切换特性/PR channel 或重现用户问题。重新安装二进制文件不会清除它；删除设备覆盖写入会清除。同样，90 天的保留期适用。
3. 插件 setChannel() 本地频道 – 当应用程序调用时创建 setChannel() 并且后端验证目标频道允许自我分配。 选择的频道在该设备上存储本地，立即生效，并不在设备覆盖UI中显示。

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

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主要版本） (取决于您的主要版本) setChannel() 它与后端联系以 验证 该频道是否允许（检查是否为该频道启用了自我分配），然后在设备上存储该频道 local channel 因为 defaultChannel. 这意味着新的频道立即生效 立即 下一次更新检查时

无需等待复制。 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分钟）才能识别新频道。新行为只从后端读取（验证）并存储本地，频道切换立即生效。 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.

创建设备覆盖项在__CAPGO_KEEP_0__控制台。设备覆盖UI只显示从控制台或公共__CAPGO_KEEP_1__创建的覆盖项。 注意：

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

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

最佳实践：

• 将1-4视为异常/测试层；当您设置云默认值时，真实用户应该流入它。如果您不设置一个，请务必明确用户如何附加（通常通过 defaultChannel 在配置文件或设备级别的覆盖中。
• 仅在配置 defaultChannel 在您明确向测试者分发的二进制文件中。
• 保持生产逻辑集中在控制台中。 setChannel() 在生产环境中使用

仅在QA或针对性的诊断中使用。

Summary: Force > Dashboard/API Override > Plugin setChannel() 总结：强制 > 控制台/覆盖 > 插件 defaultChannel 本地渠道 > 配置

Console and API overrides expire after 90 days

Forced mappings and Dashboard or Public API channel overrides are stored as per-device assignments in Capgo. A cleanup job deletes those assignments 90 天后最后一次覆盖写入检查更新时不会重置计时器。只有覆盖写入（或删除它自己）才会改变时间戳。

这不是 设备清单保留期清单会移除 90 天未连接到 Capgo 的设备。覆盖清理会移除映射，即使设备仍然活跃。

对于未被此清理移除的 assignments:

• 设置 defaultChannel 在（在重新安装时生效；需要新本机二进制才能在之后改变）。 capacitor.config.* 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，会在本地调用该 assignment。清除应用程序后会清除该 assignment，因此应用程序必须再次调用以保留该频道。
• 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，会在本地调用该 assignment。清除应用程序后会清除该 assignment，因此应用程序必须再次调用以保留该频道。 setChannel() 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，会在本地调用该 assignment。清除应用程序后会清除该 assignment，因此应用程序必须再次调用以保留该频道。 setChannel() 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，会在本地调用该 assignment。清除应用程序后会清除该 assignment，因此应用程序必须再次调用以保留该频道。

__CAPGO_KEEP_0__频道 设备 仅在控制台和公共API分配中显示。它们不显示频道上的所有设备，也不显示本地 setChannel() 分配。

频道设备选项卡上的保留期限通知。

默认频道行为

设置云端默认值是可选的，但通常作为新设备的fallback路径。没有设置默认值，仅匹配强制映射、覆盖或__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，则成为唯一的默认值；没有覆盖的设备将附加到这里 __CAPGO_KEEP_0__
• 平台特定默认值 – 如果您根据平台将渠道分开（例如，仅启用 iOS、仅启用 Android、仅启用 Electron），则将每个渠道标记为其平台的默认值。 iOS 设备将前往 iOS 默认值，Android 设备将前往 Android 默认值，Electron 应用将前往 Electron 默认值。 ios-production 请记住，云端默认值和 android-production 在 electron-production 同一决策层。 如果您设置了云端默认值，则无需在您的 __CAPGO_KEEP_0__ 配置中重复该值—在生产构建中留空。 预留

用于您故意将测试或 QA 的二进制文件发送给测试者或 QA 时，希望它们从非生产渠道开始，即使云端默认值不同。 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 Manage in App settings defaultChannel Manage

App settings Open，带您到 应用信息. 现在，通道页上的默认设置不再是开关。当您切换默认设置时，新设备立即遵循新的路由，现有设备在下一次检查时遵循正常的优先级规则。

设置通道

在入门过程中，您创建了第一个通道（大多数团队将其命名为“生产”），但没有任何内容被锁定—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 项目中。如果您跳过此同步步骤，则您的本机项目将继续使用它们之前配置的通道。

注意

通道选择顺序：强制 > Dashboard/API 设备覆盖 > 插件 setChannel() 本地通道 > 配置 defaultChannel > Cloud Default。

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

使用

Channel 名称是大小写敏感的。

Channel 选项和策略

Channels 有几个选项来控制谁可以接收更新以及如何分发更新。最重要的选项如下。您可以从 Web 应用程序、CLI 或公共 API 中配置这些选项。

• 默认频道：可选地标记新设备附加的频道或平台特定的频道。在控制台中，这个设置位于 App 信息（“在 App 设置中管理 从频道页面）。请参阅“默认频道行为”以了解路由场景。
• 平台过滤器：启用或禁用向 iOS, Android或 Electron 设备每个频道。
• 禁用原生自动降级：防止在设备的原生应用程序版本新于频道的包时发送更新（例如，设备在 1.2.3 版本，而频道有 1.2.2 版本）。
• 允许开发版本：允许更新开发版本（用于测试）。CLI: --dev / --no-dev.
• 允许生产构建：允许更新生产（商店）构建。留在开启状态，适用于服务真实用户的频道。 CLI: --prod / --no-prod.
• 允许模拟器设备：允许更新模拟器/模拟器（用于测试）。 CLI: --emulator / --no-emulator.
• 允许物理设备：允许更新真实的手机和平板电脑。留在开启状态，适用于生产频道。 CLI: --device / --no-device.
• 允许设备自我分配：让应用在运行时切换到此频道。 如果禁用， setChannel将会失败此频道。 __CAPGO_KEEP_0__: setChannel will fail for this channel. CLI: --self-assign / --no-self-assign.
• ）。参见all, zip, delta, zip_from_builtin, delta_from_builtin更新包 ，了解控制台下拉菜单和每种模式的用途。 渐进式发布

渐进式发布

A channel can maintain a stable bundle while gradually exposing a separate rollout target to a sticky device cohort. You can pause, resume, promote, roll back, and configure an automatic failure response without switching the channel for everyone. See 渐进式发布 for the delivery model, dashboard workflow, API fields, and CLI commands.

禁用自动更新策略

使用此功能来限制哪些类型的更新将自动分发。选项:

• major: 阻止目标包的主要版本号高于设备本地基线的版本号（version_buildExample: 1.2.3 -> 2.0.0 是被阻止的; 1.2.3 -> 1.9.0 是允许的。
• minor: 阻止目标包的主要或次要版本号与 version_build。 Example: 1.2.3 -> 1.3.0 被阻止; 1.2.3 -> 1.2.4 被允许。
• 修订：最严格模式。阻止任何对主要、次要或修订号的更改。仅允许后缀更改。 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如果缺失，通道将被标记为配置错误，更新将被拒绝，直到设置。
• 根据 兼容性.

这些策略将渠道的目标捆绑与本地基线进行比较，后者作为__CAPGO_KEEP_0__ version_build,而不是当前下载的捆绑作为__CAPGO_KEEP_0__ version_name.

有关详细信息和示例，请参阅 /docs/cli/commands/#disable-updates-strategy。

示例（CLI）。渠道必须已经存在（channel set 不创建它）：

# 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

# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

使用 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+)

何时 setChannel() 被调用:

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

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

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

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

频道更改方法的比较：

方法	生效时间	持久存储位置	在设备覆盖 UI 中显示	过期时间	使用场景
setChannel() 来源于插件	立即	仅设备（本地）	否	否（直到您更改或重新安装）	用户在应用内切换频道
设备覆盖面板	最多 2 分钟	后端数据库	是	最后一次覆盖写入后 90 天	针对特定设备的管理员触发的更改
API 频道分配	最多 2 分钟	后端数据库	是	最后一次覆盖写入后 90 天	自动后端集成

为了在构建频道切换 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”仪表板的“捆绑包”部分分配构建到频道。单击构建旁边的菜单图标，然后选择“分配到频道”以选择该构建的频道。

捆绑包版本和频道

请注意，Capgo中的捆绑包是全局的，针对您的应用程序，而不是针对单个频道。同一个捆绑包可以分配给多个频道。

当版本化捆绑包时，我们建议使用 语义版本控制与Capgo的Semver Tester 和预发布标识符为频道特定构建。例如，beta发布可能版本化为 1.2.3-beta.1.

在CI中，如果本地版本已经上传，则使用 npx @capgo/cli@latest bundle upload --auto-bump (可选) major, minor, patch/fix, metadata,或 ai)以使CLI从频道的链接捆绑包中升级，直到找到一个空闲的名称。 ai，Workers AI 根据本地 vs 前一次 delta manifest 推断级别（如果没有前一次 __CAPGO_KEEP_0__ 版本则回退）。 patch with no previous Capgo version). You cannot combine it with --bundle请参阅 CI/CD 集成 和 CLI 参考.

这种方法有几个好处：

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

回滚实时更新

如果您部署了一个引入了bug或需要回滚的实时更新，那么您可以轻松地回滚到之前的构建。从仪表盘的“频道”部分：

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

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

自动部署

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

查看以下 CI/CD 集成 docs to learn more about automating Capgo live updates.

最少权限的 PR 预览

使用 应用预览 API

1. Have an organization administrator create a secure API key limited to the preview app and select __CAPGO_KEEP_0____CAPGO_KEEP_0__ API.
2. 使用一个独特的、非公开的频道，如 pr-123不要传递 --default, --self-assign，发布选项，或 --delete-linked-bundle-on-upload.
3. 上传并推广 PR 包装在一个命令中，然后在 PR 关闭时删除拥有的频道和包装:

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 创建一个缺失的频道，上传包装并在一个流程中推广它。清理是原子性的，并且拥有者检查：该密钥只能删除它创建的频道及其链接的、未共享的包装。它不能改变、推广或删除一个现有的主/默认频道、另一个预览密钥的频道或另一个密钥的包装。

如果审阅者需要一个 QR 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

一个 App 预览密钥不能启用预览，因为它没有应用设置权限。在 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_KEEP_0__ 环境最佳实践：使用一个移动应用 ID 进行分阶段 Capgo 环境最佳实践：使用一个移动应用 ID 进行分阶段中的实际背景 for the practical context in Capgo Environment Best Practices: Staging with One Mobile App ID.