修复Capgo默认云频道未更新设备

更改云默认值 Capgo 新设备即刻接入。已安装的设备可能会保持原有的频道，直到下一次检查，解释了许多情况下Capgo云默认频道未更新设备的原因。

依次检查各项。首先确认设备分配，接着检查应用程序构建、同步状态、发布规则、日志和回滚设置。

目录

• 步骤 1：确认设备已分配到默认频道
• 步骤 2：检查应用程序、原生运行时和更新兼容性
• 步骤 3：验证部署实际上已到达默认频道
• 步骤 4：强制刷新同步并检查设备端日志
• 步骤 5：审查发布规则、版本门槛和自动回滚
• 步骤 6：使用实时分析找到准确的故障点
• 步骤 7：防止默认频道过时
• 常见问题
• 结论

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

目标是找出当前决定设备频道的规则。仅当更强的分配尚未将设备占据时，Cloud Default 才会生效。

打开 Capgo 面板并检查受影响设备。检查其当前频道、应用 ID、版本和最后一次登录时间。将这些值与接收预期更新的设备进行比较。这通常会快速显示问题。

频道选择遵循顺序。强制频道优先级最高。然后是面板或 API 设备的覆盖。应用程序中的本地频道设置紧随其后。然后是 Capgo 检查本地应用程序配置中的频道。Cloud Default 是最后的fallback。defaultChannel这意味着设备可以忽略更改的 Cloud Default 而无需在面板中出现错误。例如，测试构建可能仍然具有来自早期测试的本地频道。应用程序将继续使用该本地值，直到您清除它。

使用

__CAPGO_KEEP_0__ 升级调试指南 Capgo updater debugging guide 接下来，检查您的 __CAPGO_KEEP_0__ 配置。典型设置可能包括以下频道:

该字段是可选的。如果您省略它，设备可以继承 Cloud Default。这在生产构建中可能会很好，因为频道路由仍在 Capacitor 云中。如果您包含它，请确保值与您实际部署的频道匹配。

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

Capgo

Now look for local overrides in application code. A call tosetChannel()改变本地缓存。它不会创建一个后端设备覆盖。因此，仪表板可能不会显示任何覆盖，尽管应用程序仍在使用本地频道。

清除本地值时，设备应恢复正常路由。使用删除设备频道分配的插件方法，或者删除设置频道的code并重新安装应用程序进行干净测试。

关键 takeaway: 步骤 2：检查应用程序、原生运行时和更新兼容性

目标是证明已安装的应用程序可以接受您上传的包。正确的频道仍然无法将更新推送给不兼容的原生运行时。

首先是应用程序 ID。设备上安装的应用程序必须使用与您上传包的项目相同的应用程序身份。应用程序身份不匹配可能会让设备检查错误的__CAPGO_KEEP_0__应用程序，导致频道问题。

然后比较原生运行时版本与包的兼容性规则。Capgo实时更新可以更改 JavaScript、CSS 和 Web 资产，但无法添加原生插件或更改原生项目__CAPGO_KEEP_1__。原生更改仍然需要新商店构建。

Then compare the native runtime version with the bundle’s compatibility rules. Capgo live updates can change JavaScript, CSS, and web assets. They cannot add a native plugin or change native project code after the app has shipped. Native changes still need a new store build.

Think of the native runtime as the frame around the web code. If the new bundle expects a native API that the installed app does not have, Capgo should not apply it. Build and upload a compatible native version before testing that bundle.

检查已安装应用程序的版本和平台。首先在 Android 上测试 Android 包，接着在 iOS 上测试 iOS 包。另外，请确认包目标的应用程序版本，特别是在使用版本门控的渠道时。

After changingdefaultChannel更改后，请从项目根目录运行以下同步命令：

npx cap sync

此步骤将更新的配置复制到原生项目中。编辑capacitor.config而不进行同步，会使原生应用程序保留其旧的渠道设置。从该陈旧的原生项目构建新应用程序会持续产生相同的结果。

为了进行干净的测试，请在同步后构建一个新应用程序。不要依赖已安装在手机上的旧二进制文件。卸载它以清除本地渠道状态缓存，然后安装新构建并检查渠道。

The Capgo 更新行为文档 解释了更新器何时检查包。请在测试时使用该时间。启动应用程序或将其移动回前台，然后允许检查完成之前，不要认为更新失败。

另外，请检查包的原生版本门控。包可能存在于正确的渠道中，但由于其最低应用程序版本与设备不符，因此仍不可用。请在仪表盘中阅读发布详细信息，而不是假设最新上传适用于每个安装。

如果应用程序通过这些检查，说明问题已经缩小了。下一个问题是发布是否成功到达了预期的渠道。

步骤 3：确认部署实际上已经到达了默认渠道

目标是确认设备解析到的渠道中是否存在包。将包上传到一个渠道并不意味着它也会在每个渠道中可用。

在 Capgo 云中打开渠道。检查活动包、其版本和部署状态。将渠道名称与应用程序返回的值进行比较。注意小差异，如productionversusprod。

If you deploy through CI/CD, inspect the command output from the same job that uploaded the bundle. Confirm the app ID and channel passed to the CLI. A pipeline can finish with a successful upload while targeting a staging channel by mistake.

如果您通过 CI/CD 部署，请检查同一工作流程中上传包的命令输出。确认应用 ID 和渠道传递给 __CAPGO_KEEP_0__。一条管道可能会以成功上传的方式结束，而实际上却是错误地将包上传到一个测试渠道。

检查包的状态。草稿或未激活的发布可能在仪表板中可见，但对设备不可用。如果渠道有一个阶段性发布，受影响的设备可能不会满足其发布规则。

Capgo的实时OTA引擎是为web层变化而设计的。它可以移动一个JavaScript包、CSS或资产更新，而不需要等待新的商店审查。这种速度取决于发布是否在设备检查的准确频道中处于活动状态。

如果您刚刚更改了Cloud Default，请记住设备的时间表。新安装使用新的路由立即生效。现有设备通常在下一次更新检查时切换。关闭并重新打开应用程序可以帮助触发检查，但无法覆盖固定频道。

现在在应用程序内部验证结果。调用getChannel()在更新器启动后调用。记录返回的频道旁边的应用程序版本和包版本。这比仅检查仪表盘更有用，因为它显示设备所信任的频道。

如果应用程序只在启动或前台时检查，应预计会有延迟。不要通过打开永不启动的屏幕来测试。将检查放在一个短测试构建的已知启动路径中，然后在发布前移除额外的日志。

如果返回的频道正确但没有包到达，请转到兼容性和滚动规则。如果返回的频道错误，请返回步骤1并清除胜过Cloud Default的赋值。

步骤4：强制刷新同步并检查设备侧日志

目标是分离陈旧的本地状态和服务器端交付问题。一次新的检查会给您新的证据。

首先，确保设备有网络访问。成功的应用会话并不能证明更新器能到达其端点。公司过滤器、VPN规则、捕获门户或过期会话可以阻止更新请求。

接下来，将应用带到前台。等待更新器检查完成。如果您的应用暴露了更新状态事件，请将该事件与当前频道一起记录。避免只记录“更新开始”。您需要知道应用是否找到包、下载它、验证它、安装它，还是拒绝它。

使用Capgo的设备日志来找到第一个失败的阶段。第一个错误通常比最终的“更新失败”消息更有用。例如，缺少频道指向路由。兼容性拒绝指向本机运行时或版本门户。下载错误指向网络访问或包请求。

重新安装是一个有用的测试，但它会改变证据。重新安装可能会清除本地渠道状态。请在捕获当前渠道和日志后再使用它，不要在前面。

为了可重复的检查，请在一行日志中记录这些值：

• 应用 ID 和原生应用版本
• 从以下来源解析的渠道getChannel()
• 最后一次更新检查时间
• 服务器端发现的包版本
• 安装或拒绝结果

这个小记录有助于在设备属于无法在需求时重现问题的测试者时帮助诊断问题。它还为 CI 团队提供了自动化烟雾测试的明确信号。

Use the official Capgo Capacitor Updater source repository when you need to inspect the plugin API behavior. In particular, pay attention to the difference between a local channel change and a dashboard device assignment.

Pro Tip: 在清除之前捕获解析的渠道。否则，您可能会修复状态并丢失解释失败的线索。

步骤 5: 检查发布规则、版本门槛和自动回滚

目标是检查 Capgo 是否故意阻止或逆转了包。缺失的更新有时是安全规则正在按设计工作。

打开渠道设置并检查与发布关联的每个规则。查找最小应用版本、百分比发布设置、设备过滤器和与发布关联的条件。设备不符合规则将保持其当前包，即使渠道正确。

检查版本格式。Capgo 使用语义版本来比较发布。一个看起来正确的版本门控仍然会表现出不同行为，如果应用或捆绑使用了意外的格式。保持格式一致，跨原生构建和OTA发布。

然后检查回滚行为。自动回滚可能会将设备回滚到之前的捆绑包，失败的健康检查后。仪表盘可能会显示较旧的活动code，而您期望的发布仍然存在但不可用。

不要在未查看事件之前删除可疑的捆绑包。删除会移除有用的证据。首先记录捆绑包版本、频道、发布状态和回滚原因。然后决定是否暂停发布或发布已知的良好版本。

使用分阶段频道进行风险变更。首先将捆绑包发送到小型测试组。监控采用率和错误信号。发布行为如预期后，继续发布。这可以防止一次性将坏的Web层变更推送到每个活动设备。

回滚只会修复code，OTA可以改变的部分。如果失败来自缺失的原生插件或不兼容的原生API，您需要一个新的商店构建。发送较旧的JavaScript捆绑包不会添加应用缺少的原生部分。

当您检查规则时，问三个问题：

• 这个设备是否满足应用版本条件？
• 设备是否位于发布组内？
• 健康检查或手动操作是否将其回滚到较旧的捆绑包？

Capgo 在这里很有用，因为同一个频道模型可以携带一个阶段性发布、支持回滚和在一个工作流中显示更新活动。保持规则集小。短的策略比在事故期间建立的异常堆栈更容易审计。

If you need API-based checks, the Capgo 公开的 API 文档 描述了设备、频道和捆绑包的资源。使用它来比较服务器视图与应用程序报告的内容。这种比较可以揭示一个过时的仪表板过滤器或由自动化创建的设备分配。

回滚是一个安全栅栏，而不是测试的替代品。保持每个生产频道中有一个已知良好的捆绑包。

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

目标是停止将“未更新”视为一个故障。分析可以显示设备是否从未检查入、找不到可用的捆绑包、下载失败或后来回滚。

从受影响的设备组开始。过滤应用程序版本、平台、频道和捆绑包版本。寻找模式。如果只有一个旧应用程序构建失败，问题可能是本机兼容性门限。如果每个设备在一个频道中失败，请检查频道或部署。

比较采用率随时间的变化。发布后出现的平坦线表明路由或资格问题。上升后下降表明安装错误或回滚。缓慢上升可能仅仅意味着设备尚未打开应用程序。

谨慎使用时间戳。仪表盘事件时间可能与用户的本地时间不同。将更新事件与设备的最后一次检查时间匹配。这在测试者说更新失败之前，应用程序实际上已经检查过时非常有用。

分析还可以让您安全地测试通道更改。一次更改一个变量。保持捆绑包的常数，同时测试路由。然后保持路由的常数，同时测试新捆绑包。如果您同时更改两个，数据无法告诉您哪个更改解决了问题。

对于一个事件，保存一个小的证据集：

• 设备标识符或内部测试标签
• 已解决的通道
• 原生应用程序版本
• 预期捆绑包和安装的捆绑包
• 最后一次检查时间
• 回滚或拒绝事件

Capgo的实时视图在您的发布过程通过CI/CD发送更新时最有用。一个部署作业可以上传一个捆绑包，而一个监控步骤可以检查测试设备报告的预期通道和捆绑包。这样就把手动抱怨转化为发布门槛。

将分析数据与发布记录绑定。将提交或构建引用写入您的部署笔记。当两个捆绑包具有类似的版本标签时，构建引用告诉您哪个code实际上移动了。

如果只有现有设备在更改Cloud Default后失败，等待它们的下一次检查时间再更改其他设置。一个新安装是一个有用的控制。它告诉您是否默认路由对于没有旧本地状态的设备有效。

第 7 步：防止默认频道过期

目标是在用户受影响之前使频道漂移可见。一个小的发布清单可以防止大多数重复案例。

为每个应用环境选择一个路由模型。对于生产环境，您可能可以省略defaultChannel并让Capgo Cloud控制默认值。对于测试构建，您可能可以设置一个明确的频道。危险的设置是混合了旧的本地覆盖、陈旧的本地配置和新的 Cloud 默认值，而没有人验证。

在构建路径中npx cap sync配置更改后添加。让构建失败，如果同步步骤失败。命令很简单，但跳过它可以将昨天的频道烘焙到今天的本机二进制中。

在部署后添加一个烟雾测试。测试设备应该启动应用程序，调用getChannel()，检查预期的捆绑包，并记录结果。验证往往是 OTA 工作流中的缺失步骤。仅仅上传证明很少。

将本地频道code置于清晰的特性标志之后。如果测试助手调用setChannel()，确保生产构建不能包含它。记住，缓存可能不会显示为仪表板覆盖，因此 UI 不能捕捉到每个问题。

使用以下发布清单:

1. 确认应用 ID 和本机版本。
2. 选择目标频道。
3. 将包上传到该频道。
4. 确认包处于活动状态。
5. 运行设备烟雾测试。
6. 检查返回的频道与getChannel().
7. 观察采用率之前扩大发布范围。

生产发布时保持回滚保护功能。常见的故障模式是部署时没有明确的频道或回滚计划。这会使团队在发布时有更少的安全方式来停止坏包。

Capgo 使用组织订阅，提供 14 天的免费试用期。将试用期视为测试真实应用构建的发布流程，而不是仅仅检查仪表板。尝试一次分阶段部署、一次回滚测试和一次自动频道检查。

安全性应包含在同一检查清单中。保护 CI/CD 令牌。限制更改 Cloud Default 的用户。将生产部署凭据从本地脚本中移除。未经授权的频道更改可能会看起来像过时的设备，直到您查看审计记录。

对于频繁发布的团队，保持过程简单。一个命令部署。一个已知的测试设备。一个明确的频道规则。跟踪、采用、回滚。

关键 takeaway: 防止过时的路由通过同步配置、避免本地隐藏的覆盖、测试解析的频道和保持回滚准备就绪。

常见问题

为什么 Capgo 云默认频道无法更新已有设备?

已有设备可能会保留旧频道直到下一次更新检查。 本地频道、控制台覆盖或强制分配也可能优先于 Cloud Default。 确认设备的解析频道并且getChannel()清除任何更强的分配，然后将应用程序置于前台。

改变 Capgo 云默认频道会影响所有已安装的应用吗?

不，改变 Cloud Default 不会立即重写每个应用程序的频道设置。 新设备可以立即使用新的默认值。 已安装的应用程序需要在检查后才能切换，除非更强的频道规则或本地覆盖应用。

npx cap sync 对于 Capgo 频道更改会做什么?

npx cap sync将更新的 Capacitor 配置复制到本机项目中。 如果您跳过同步，下一次本机构建可能仍然包含旧频道设置。 从项目根目录运行命令，然后构建并安装一个新鲜的测试二进制文件。defaultChannelsetChannel 会在 __CAPGO_KEEP_0__ 中创建一个设备覆盖吗?

Does setChannel create a device override in Capgo?

会改变本地存储的频道设置。 它不会创建一个后端的设备覆盖，因此 __CAPGO_KEEP_0__ 控制台可能不会显示设备被覆盖。 清除本地分配时设备应该返回到默认路由，然后验证结果。setChannel()changes the channel stored locally by the app. It does not create a backend Device Override, so the Capgo dashboard may not show the device as overridden. Clear the local assignment when the device should return to default routing, then verify the result withgetChannel().

Can Capgo 更新本机 code 通过 OTA 包?

No, Capgo OTA 更新只适用于 Web 层 code，如 JavaScript、CSS 和资产。需要新建应用商店包的有本机插件、权限或本机 API 变更。如果 OTA 包期望的本机 code 与已安装应用程序不符，更新可能会被拒绝，即使通道正确。

结论

首先从已解析的通道开始，而不是从仪表板默认值开始。检查分配，运行npx cap sync, 验证 OTA 包与本机运行时的兼容性，并检查设备日志，然后修改发布规则。最后，在 Capgo 中添加一个小型 post-deploy 测试，调用getChannel()并确认预期的 OTA 包。