频道

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

频道不提供保密性

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

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

当设备检查更新时，Capgo会在以下严格顺序（优先级最高）中选择频道：

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

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

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主要版本） (取决于您的主要版本) setChannel() 它与后端通信以 验证 该频道是否允许（检查是否为该频道启用了自我赋值），然后在设备上存储该频道 __CAPGO_KEEP_0__ 因为 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).旨在为测试者提供内部构建的预发布频道。生产构建通常不设置此值。
5. 云默认频道（主要路径~99%的用户) – 如果在控制台中标记了默认频道，则所有正常用户（无强制、无控制台/API覆盖、无插件本地频道、无配置defaultChannel）将附加到此频道。更改它以立即推出或回滚—无需新二进制文件。如果您有平台特定的默认值（例如，一个iOS-only，一个Android-only，一个Electron-only），则每个设备将在其平台匹配的默认值下启动。未设置云默认值是允许的；在这种情况下，设备必须匹配步骤1-4才能接收更新。

最佳实践：

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

如果一个渠道在平台（iOS/Android/Electron切换）上被禁用，而它本应该被选择，那么选择过程会跳过它并继续下一项。

总结：强制 > 控制台/ API 覆盖 > 插件 setChannel() 本地渠道 > 配置 defaultChannel > 云默认。

控制台和 API 覆盖在90天后过期

强制映射和控制台或公共 API 渠道覆盖存储为 Capgo 设备 assignments。清理作业删除这些 assignments 90 天后最后一次覆盖写入检查更新时不会重置计时器。只有覆盖写入（或删除它自己）才会改变时间戳。

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

对于未被清理删除的分配:

• 设置 defaultChannel 在（在重新安装时生效；需要新本机二进制才能在以后改变）。 capacitor.config.* 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，分配是本地的，并不会被清理删除。重新安装应用程序会清除它，所以应用程序必须再次调用 __CAPGO_KEEP_1__，如果您仍然希望使用该频道。
• 设置 setChannel() 在（在重新安装时生效；需要新本机二进制才能在以后改变）。 setChannel() 从应用程序中调用。从 Capgo 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本的插件中，分配是本地的，并不会被清理删除。重新安装应用程序会清除它，所以应用程序必须再次调用 __CAPGO_KEEP_1__，如果您仍然希望使用该频道。

__CAPGO_KEEP_0__ 设备 仅在控制台和公共API assignments中显示。它们不显示所有设备，且不显示本地 setChannel() __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ Devices tab上的Override保留提示

默认频道行为

设置云端默认值是可选的，但通常作为新设备的通用路径。没有一个，仅匹配强制映射、覆盖或__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人员时，尽管云端默认值不同。 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）。对于生产构建，建议省略它，以便设备使用 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 您仍然可以强制（固定）一个设备或应用一个覆盖—那些立即超越配置值。

Use

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 package 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。如果缺失，会将该频道标记为配置错误，更新将被拒绝，直到设置为正确。
• 允许所有更新，根据 的兼容性.

这些策略将渠道的目标捆绑与本地基线进行比较，后者作为 version_build,而不是当前下载的捆绑作为 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
});

如何设置 Channel() 工作 (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 channel. 任何配置为监听该频道的应用都会在下一次检查更新时接收到更新。

您还可以从“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__版本）。您无法将其与”，“合并。请参阅”，“CI/CD Integration”，“（CI/CD Integration），上下文：Capgo Builder / 原生云构建产品页面。角色：短 UI 标签或导航项。消息键 `native_build_feature_ci_cd`（Native Build Feature Ci Cd）。”，“和”，“__CAPGO_KEEP_0__参考”，“这种方法有几个好处：”，“它清晰地传达了构建之间的关系。”，“显然是”，“的预发布版本。”，“它允许在通道之间重用版本号，减少混淆。”，“它使回滚路径清晰。如果您需要从”，“回滚，您知道”]}] } patch with no previous Capgo version). You cannot combine it with --bundleSimplified Chinese pagePath /zh/docs/live-updates/channels/ CLI reference.

["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"]

• items 1.2.3-beta.1 [{"text":", Workers AI infers the level from the local vs previous delta manifest (falls back to","text":"with no previous __CAPGO_KEEP_0__ version). You cannot combine it with","text":". See","text":"CI/CD Integration","context":"Page/area: Capgo Builder / native cloud build product page. Role: Short UI label or navigation item. Message key `native_build_feature_ci_cd` (Native Build Feature Ci Cd).","text":"and the","text":"__CAPGO_KEEP_0__ reference","text":"This approach has several benefits:","text":"It clearly communicates the relationship between builds.","text":"is obviously a pre-release of","text":"It allows for reusing version numbers across channels, reducing confusion.","text":"It enables clear rollback paths. If you need to roll back from","text":"", you know"}] 1.2.3.
• items
• [{"text":"，Workers AI 根据本地 vs 前次 delta manifest 推断级别（回退到","text":"，没有前次__CAPGO_KEEP_0__版本）。您无法将其与","text":"合并。请参阅","text":"CI/CD Integration","context":"Page/area: Capgo Builder / 原生云构建产品页面。角色：短 UI 标签或导航项。消息键 `native_build_feature_ci_cd`（Native Build Feature Ci Cd）。","text":"和","text":"__CAPGO_KEEP_0__参考","text":"这种方法有几个好处：","text":"它清晰地传达了构建之间的关系。","text":"显然是","text":"的预发布版本。","text":"它允许在通道之间重用版本号，减少混淆。","text":"它使回滚路径清晰。如果您需要从","text":"回滚，您知道"}] 1.2.3targetLanguage 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集成到您的构建过程中，您可以自动上传新的捆绑包并将其分配到频道，任何时候您推送到特定分支或创建新版本时。

查看以下 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__。请参阅 API Keys.
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测试
• 逐步功能发布
• 测试版发布计划

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

继续使用渠道

如果您正在使用 渠道 为 Channel 路由和阶段性发布做好规划，连接它 Channels Channels Channels Channels Beta 测试解决方案 为 Beta 测试解决方案中的产品工作流做好规划 版本目标解决方案 为版本目标解决方案中的产品工作流做好规划 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期 为 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期中的实际背景做好规划