修复 Capgo 默认频道不更新设备的问题

更改 Cloud Default 于 Capgo 全新设备会立即路由到该渠道。已安装的应用可能仍停留在旧渠道，直到再次检查更新，这解释了很多 Capgo 云默认渠道无法更新设备的情况。

按顺序逐项检查。先确认设备分配，再检查应用构建、同步状态、发布规则、日志和回滚设置。

目录

• 步骤 1：确认设备已分配到默认 Channel
• 步骤 2：检查 App、原生运行时和更新兼容性
• 步骤 3：验证部署是否确实到达默认渠道
• 第 4 步：强制重新同步并检查设备端日志
• 步骤 5：审查 Rollout 规则、版本门控和自动回滚
• 步骤 6：使用实时分析找到确切的故障点
• 步骤 7：防止默认渠道过期
• 常见问题
• 总结

步骤 1：确认设备已分配到默认 Channel

目标是找出当前是哪条规则决定了设备的通道。只有在更强的分配尚未占用该设备时，Cloud Default 才会生效。

打开 Capgo dashboard，检查受影响的设备。查看其当前通道、App ID、版本和最后 check-in 时间。将这些值与收到预期更新的设备对比。这种对比通常能快速定位问题。

通道选择遵循顺序：强制通道优先级最高，其次是 dashboard 或 API 的设备覆盖，然后是应用设置的本地通道，随后由 Capgo 检查defaultChannel在原生应用配置中。Cloud Default 是兜底值。

这个顺序意味着设备可以忽略已更改的 Cloud Default，而 dashboard 不会报任何错。例如，测试构建可能仍带有之前测试留下的本地 channel。在清除它之前，应用会一直使用该本地值。

使用 Capgo updater 调试指南 当解析出的 channel 为空或不符合预期时。它涵盖应用没有可用默认值、设备也没有 override 的情况。

接下来，检查你的 Capacitor 配置。典型配置可能包含如下 channel：

const config = { plugins: { CapacitorUpdater: { defaultChannel: 'production' } }
}

该字段可选。省略后，设备可以继承 Cloud Default。这对生产构建很合适，因为 channel 路由仍留在 Capgo Cloud 中。如果填了，请确保该值与你实际部署的 channel 一致。

现在查找应用 code 中的本地 override。调用setChannel()会修改本地缓存。它不会创建后端 Device Override。因此，即使应用仍在使用本地 channel，dashboard 也可能显示没有 override。

当设备应恢复正常路由时，请清除该本地值。使用移除设备 channel 分配的 plugin 方法，或者移除设置 channel 的 code，然后重新安装应用，做一次干净的测试。

核心要点： 已更改的 Cloud Default 无法取代优先级更高的设备、应用或本地 channel 分配。

步骤 2：检查 App、原生运行时和更新兼容性

目标是验证已安装的应用能否接收你上传的 bundle。即使 channel 配置正确，如果原生运行时不兼容，也无法下发更新。

从 App ID 开始检查。设备上安装的 App 必须使用与上传 bundle 的项目相同的 App 身份。不匹配可能看起来像 channel 问题，因为设备检查了错误的 Capgo App。

然后比较原生运行时版本与 bundle 的兼容性规则。Capgo live updates 可以更改 JavaScript、CSS 和 Web 资源。它们无法在 App 发布后添加原生插件或更改原生项目 code。原生更改仍需新的商店构建。

将原生运行时视为围绕 Web code 的框架。如果新 bundle 期望的原生 API 是已安装 App 所没有的，Capgo 不应应用它。在测试该 bundle 之前，构建并上传兼容的原生版本。

检查已安装 App 的版本和平台。先在 Android 上测试 Android bundle。在 iOS 上测试 iOS bundle。如果您的 channel 使用版本门控，还请确认 bundle 针对正确的 App 版本。

更改后defaultChannel，从项目根目录运行同步命令：

npx cap sync

此步骤将更新后的配置复制到原生项目中。编辑capacitor.config不同步会导致原生 App 保留旧的 channel 设置。从该过时的原生项目进行的最新构建将继续产生相同的结果。

为了干净的测试，同步后构建新 App。不要依赖手机上安装的旧二进制文件。当需要清除缓存的本地 channel 状态时，卸载它，然后安装新构建并再次检查 channel。

本指南中介绍的 Capgo 更新行为文档 说明更新器何时检查 bundle。测试时请利用这一时机。启动应用或将其切回前台，然后等待检查完成，再判断更新是否失败。

同时检查 bundle 的原生版本门槛。即使 bundle 存在于正确的 channel 中，如果其最低应用版本与设备不匹配，它仍可能不可用。请在 dashboard 中查看发布详情，不要假设最新上传的 bundle 适用于所有安装。

如果应用通过了这些检查，你就缩小了故障范围。下一个问题是：这个 release 到底有没有到达预期的 channel。

步骤 3：验证部署是否确实到达默认渠道

目标是确认 bundle 存在于设备解析到的 channel 中。将 bundle 上传到一个 channel 并不意味着它在所有 channel 中都可用。

在 Capgo Cloud 中打开该 channel。检查当前生效的 bundle、其版本和部署状态。将 channel 名称与应用返回的值进行对比。注意细微差异，例如production与prod。Channel 名称必须完全匹配。

如果你通过 CI/CD 部署，请检查上传 bundle 的同一 job 的命令输出。确认传给 CLI 的 app ID 和 channel。Pipeline 可能成功上传，但错误地指向了 staging channel。

接下来检查 bundle 的状态。草稿或未激活的发布可能在 dashboard 中可见，但设备无法获取。如果该 channel 配置了分阶段发布（staged rollout），受影响的设备可能不满足其发布规则。

使用一台已知的测试设备，并为其分配明确的角色。例如，将一台设备固定（pin）到测试 channel，另一台设备保留在 Cloud Default。上传一个无害的更改，然后对比它们的 check-in 记录。这样可以消除测试中的猜测成分。

Capgo 的实时 OTA 引擎专为 Web 层更改设计。它可以在无需等待新的应用商店审核的情况下，推送 JavaScript bundle、CSS 或资源更新。这种速度取决于发布在设备检查的确切 channel 中处于激活状态。

如果你刚刚更改了 Cloud Default，请记住设备的时序。新安装会立即使用新路由。现有设备通常在执行下一次更新检查时切换。关闭并重新打开应用可能有助于触发该检查，但无法覆盖已固定的 channel。

现在在应用内验证结果。调用getChannel()在 updater 启动后。将返回的 channel 记录在应用版本和 bundle 版本旁边。这比仅检查 dashboard 更有用，因为它显示了设备认为的状态。

如果应用只在启动或回到前台时检查更新，就可能出现延迟。不要通过打开一个根本不会启动更新器的页面来测试。在用于短测的构建中，把检查逻辑放在已知的启动路径里，发布前再移除额外日志。

如果返回的 channel 正确，却没有收到 bundle，就转到兼容性和发布规则。如果返回的 channel 错误，请回到第 1 步，并清除优先于 Cloud Default 的分配。

第 4 步：强制重新同步并检查设备端日志

目标是把过期的本地状态与服务端下发问题区分开。一次全新的检查能提供新证据。

首先，确保设备能访问网络。应用会话成功并不代表更新器能访问其 endpoint。企业网络过滤、VPN 规则、强制门户或会话过期都可能拦截更新请求。

接下来，把应用切回前台。等待更新检查完成。如果你的应用会提供更新状态事件，请记录该事件和当前 channel。不要只记录“update started”。你需要知道应用是找到了 bundle、下载了、验证了、安装了，还是拒绝了。

使用 Capgo 的设备日志找出首个失败阶段。第一个错误通常比最后的“update failed”消息更有用。例如，channel 缺失说明是路由问题；兼容性拒绝说明是 native runtime 或版本门槛问题；下载错误说明是网络访问或 bundle 请求问题。

重装是有用的测试，但会改变证据。重装可能清除本地 channel 状态。请在抓取当前 channel 和日志后再重装，不要提前。

为了便于重复检查，请将以下值记录在同一行日志中：

• App ID 和原生应用版本
• 解析出的 Channel 来源getChannel()
• 上次 Updater 检查时间
• 服务器找到的 Bundle 版本
• 安装或拒绝结果

当设备属于无法按需复现问题的测试人员时，这条小记录很有帮助。它也为 CI 团队提供了自动化冒烟测试的明确信号。

如需检查插件 API 的行为，请使用官方的 Capgo Capacitor Updater 源码仓库。尤其要注意本地 Channel 变更与 Dashboard 设备分配之间的区别。

专家提示： 在清除前记录下解析出的 Channel。否则，你可能修复了状态，却丢失了解释故障的线索。

步骤 5：审查 Rollout 规则、版本门控和自动回滚

目标是检查 Capgo 是否有意扣留或回退了 Bundle。有时，没有更新恰恰是安全规则在按设计生效。

打开 Channel 设置，检查该 Release 关联的所有规则。留意最低应用版本、百分比 Rollout 设置、设备筛选条件以及与 Release 绑定的条件。即使 Channel 正确，不符合规则的设备仍会停留在当前 Bundle。

同时检查版本格式。Capgo 使用语义化版本比较发布版本。版本门控看起来没问题，但如果应用或 bundle 使用了意外格式，实际行为仍可能不同。请确保原生构建和 OTA 发布使用一致的格式。

然后检查回滚行为。健康检查失败后，自动回滚可能会把设备回退到之前的 bundle。dashboard 可能显示较旧的活跃 code，而你预期的发布版本仍然存在但不可用。

在查看可疑 bundle 的事件之前，不要删除它。删除会丢失有用的证据。先记录 bundle 版本、channel、rollout 状态和回滚原因，再决定暂停发布还是发布一个已知可用的版本。

对高风险变更使用分阶段 channel。先把 bundle 发给小型测试组。关注采用率和错误信号。一旦发布表现符合预期，再推进 rollout。这样可避免有问题的 web 层变更一次性到达所有活跃设备。

回滚只能修复 code 中 OTA 可修改的部分。如果故障源于缺失的原生插件或不兼容的原生 API，你需要一个新的商店构建版本。发送旧的 JavaScript bundle 无法补全应用缺失的原生组件。

检查规则时，请思考三个问题：

• 该设备是否满足应用版本条件？
• 该设备是否在发布组内？
• 健康检查或手动操作是否将其回退到了旧的 bundle？

Capgo 在此处很有用，因为相同的 channel 模型可以承载分阶段发布、支持回滚，并在一个工作流中显示更新活动。保持规则集精简。简短的策略比事故期间构建的一堆例外更容易审计。

如果你需要基于 API 的检查，请参见 Capgo 公共 API 文档 描述了设备、channel 和 bundle 的资源。使用它来对比服务器视图与应用报告的内容。这种对比可以揭示过时的 dashboard 过滤器或由自动化创建的设备分配。

回滚是护栏，而非测试的替代品。在每个生产 channel 中保留一个已知良好的 bundle。

步骤 6：使用实时分析找到确切的故障点

目标是将“未更新”视为多种不同的故障，而非单一问题。Analytics 可以显示设备是未检查、未找到符合条件的 bundle、下载失败，还是后来发生了回滚。

从受影响的设备组开始。按 app 版本、平台、channel 和 bundle 版本进行筛选。寻找规律。如果只有一个旧 app build 失败，问题可能是原生兼容性门槛。如果某个 channel 中的所有设备都失败，请检查该 channel 或部署情况。

比较随时间变化的采用率。发布后曲线持平，表明路由或资格判定有问题。先升后降，表明安装错误或回滚。缓慢上升可能仅意味着设备尚未打开 app。

谨慎使用时间戳。Dashboard 上的事件时间可能与用户本地时间不同。将更新事件与设备的最后 check-in 时间进行匹配。当测试人员说更新失败时，这有助于确认 app 是否实际执行了检查。

Analytics 还能帮助你安全地测试 channel 变更。每次只改变一个变量。测试路由时保持 bundle 不变。测试新 bundle 时保持路由不变。如果同时更改两者，数据将无法告诉你哪个变更解决了问题。

对于事故，请保存一组小型证据集：

• 设备标识符或内部测试标签
• 解析后的 channel
• 原生应用版本
• 预期 bundle 和已安装 bundle
• 最后 check-in 时间
• 回滚或拒绝事件

Capgo 的实时视图在通过 CI/CD 发送更新时最为有用。部署任务可以上传 bundle，而监控步骤可以检查测试设备是否报告了预期的 channel 和 bundle。这将手动投诉转化为发布门禁。

将分析数据与发布记录关联。在部署说明中写入 commit 或 build 引用。当两个 bundle 的版本标签相似时，build 引用能告诉你哪个 code 实际发生了变更。

如果仅在更改 Cloud Default 后现有设备失败，请在更改更多设置前等待它们下次 check-in。新安装是一个有用的对照。它告诉你默认路由对于没有旧本地状态的设备是否有效。

步骤 7：防止默认渠道过期

目标是在 channel 漂移影响用户之前使其可见。一个简单的发布检查清单可以防止大多数重复案例。

为每个应用环境选择一种路由模型。对于生产环境，你可以省略defaultChannel并让 Capgo Cloud 控制默认值。对于测试构建，你可以设置显式 channel。危险的配置是旧的本地覆盖、过时的原生配置和无人验证的新 Cloud Default 的混合。

放置npx cap sync在配置更改后的构建路径中。如果同步步骤失败，使构建失败。命令很简单，但跳过它可能会将昨天的 channel 烘焙到今天的原生二进制文件中。

在部署后添加冒烟测试。测试设备应启动应用，调用getChannel()，检查预期的 bundle，并记录结果。验证往往是 OTA 工作流中缺失的一环。仅上传本身几乎不能证明任何问题。

将本地 channel code 置于清晰的功能标志（feature flag）之后。如果测试辅助函数调用了setChannel()，请确保生产构建不会意外包含它。请记住，本地缓存可能不会显示为 dashboard 覆盖，因此 UI 无法捕获所有问题。

使用如下发布检查清单：

1. 确认应用 ID 和原生版本。
2. 选择目标 channel。
3. 将 bundle 上传到该 channel。
4. 确认 bundle 已激活。
5. 运行设备冒烟测试。
6. 使用以下命令检查返回的 channel：getChannel().
7. 在扩大 rollout 范围前，先关注采用情况。

生产环境发布时请保持回滚保护开启。常见的故障模式是在没有明确 channel 或回滚计划的情况下部署，这会让团队缺少安全停止问题 bundle 的手段。

Capgo 采用按组织订阅的模式，提供 14 天免费试用。请把试用期当作在真实应用构建上测试发布流程的机会，而不只是看看 dashboard。试着做一次分阶段部署、一次回滚测试和一次自动化 channel 检查。

安全也应列入同一份检查清单。保护好 CI/CD token。限制可以修改 Cloud Default 的人员。不要把生产部署凭证放进本地脚本。未经授权的 channel 变更，在你查看审计日志之前，看起来可能只是设备状态陈旧。

对于频繁发布的团队，让流程保持简单可预测。一条命令完成部署。一台固定的测试设备。一条清晰的 channel 规则。跟踪、采用、回滚。

核心要点： 通过同步配置、避免隐藏的本地覆盖、测试解析后的 channel，并保持回滚就绪，来防止路由过期。

常见问题

为什么 Capgo 云默认通道没有更新现有设备？

现有设备可能会保留旧通道，直到下一次更新检查。本地通道、dashboard 覆盖或强制分配也可能优先于云默认通道。请使用getChannel()确认设备解析后的通道，清除任何更强的分配，然后将应用置于前台。

更改 Capgo 云默认通道会改变所有已安装的应用吗？

不，更改 Cloud Default 不会立即重写所有已安装应用的 channel。新设备可以立即使用新的默认值。现有安装需要 check in 后才能切换，如果存在更强的 channel 规则或本地 override，它们仍然不会切换。

npx cap sync 对 Capgo channel 变更有什么作用？

npx cap sync将更新后的 Capacitor 配置复制到原生项目中。如果你更改了defaultChannel但跳过了 sync，下一次原生 build 可能仍包含旧的 channel 设置。请在项目根目录运行该命令，然后 build 并安装一个新的测试二进制文件。

setChannel 会在 Capgo 中创建设备 override 吗？

不，setChannel()更改的是应用本地存储的 channel。它不会创建后端的 Device Override，因此 Capgo dashboard 可能不会显示该设备为 overridden。当设备应返回默认路由时，清除本地分配，然后使用getChannel().

Capgo 能通过 OTA bundle 更新原生 code 吗？

不，Capgo OTA 更新仅适用于 web 层的 code，例如 JavaScript、CSS 和资源。原生插件、权限或原生 API 的变更需要新的 store build。如果 bundle 期望的原生 code 在已安装应用中缺失，即使 channel 正确，更新也可能被拒绝。

总结

从解析后的 channel 开始，而不是 dashboard 默认值。检查 assignments，运行npx cap sync，验证 bundle 与原生 runtime 的兼容性，并在更改 rollout 规则前检查设备 logs。然后在 Capgo 中添加一个小型部署后测试，调用getChannel()并确认预期的 bundle。