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

更改__CAPGO_KEEP_0__云端默认 Capgo 新设备会立即接收到最新的更新，而已安装的设备可能会保持原有的频道，直到下一次同步更新，这也解释了为什么Capgo云端默认频道未更新设备的原因

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

目录

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

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

目标是找出当前决定设备频道的规则。 只有当没有更强的分配已经占据设备时，Cloud Default 才会生效。

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

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

使用

使用 Capgo 设备更新调试指南 第 7 步：防止默认频道过期

接下来，检查您的Capacitor配置。典型的设置可能包括一个类似这样的频道：

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

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

现在查找应用程序code中的本地覆盖。对setChannel()会更改本地缓存。它不会创建一个后端设备覆盖。因此，仪表板可能会显示没有覆盖，尽管应用程序仍在使用本地频道。

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

关键 takeaway： 一个改变的Cloud Default不能替代一个更强的设备、应用程序或本地频道的分配。

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

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

从应用程序 ID 开始。设备上安装的应用程序必须使用与您上传捆绑包的项目相同的应用程序身份。应用程序身份不匹配可能会看起来像频道问题，因为设备检查的应用程序是错误的Capgo

然后比较原生运行时版本与捆绑包的兼容性规则。 Capgo 实时更新可以更改 JavaScript、CSS 和 Web 资产。它们不能添加原生插件或更改原生项目 code 之后应用程序已发布。原生更改仍然需要新商店构建。

想象原生运行时为 Web code 周围的框架。如果新捆绑包期望的原生 API 与已安装应用程序不符， Capgo 不应应用它。 在测试捆绑包之前，构建并上传兼容的原生版本。

检查已安装应用程序的版本和平台。首先在 Android 上测试 Android 捆绑包，测试 iOS 捆绑包在 iOS 上。另外，请确认捆绑包针对正确的应用程序版本，当您的频道使用版本门控时。

更改后defaultChannel运行以下命令从项目根目录：

npx cap sync

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

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

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

也检查捆绑包的原生版本门槛。捆绑包可以存在于正确的频道中，但仍不可用，因为其最低应用程序版本与设备不符。请在仪表板中阅读发布详细信息，而不是假设最新上传适用于每个安装。

如果应用程序通过这些检查，已缩小故障范围。下一个问题是发布是否已达到预期频道。

步骤 3：验证部署实际已到达默认频道

目标是确认捆绑包存在于设备解析的频道中。将捆绑包上传到一个频道并不使其在每个频道中可用。

在 Capgo 云中打开频道。检查活动捆绑包、其版本和其部署状态。将频道名称与应用程序返回的值进行比较。注意小差异，如production versus prod。频道名称必须完全匹配。

如果您通过 CI/CD 部署，请检查同一作业上传捆绑包的命令输出。确认应用程序 ID 和频道传递给 CLI。管道可以以成功上传的方式完成，而错误地将目标频道设置为测试频道。

检查捆绑包的状态。草稿或未激活的发布可能在仪表盘中可见，但对设备不可用。如果频道有阶段性发布，受影响的设备可能不符合发布规则。

使用一个已知的测试设备。为其分配一个明确的角色。例如，将一个设备固定到测试频道，另一个设备留在Cloud Default。上传一个无害的更改，然后比较它们的检查记录。这消除了测试中的猜测。

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

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

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

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

如果返回的频道正确但没有包到达，请转到兼容性和发布规则。如果返回的频道错误，请返回步骤1并清除Cloud Default中获胜的分配。

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

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

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

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

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

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

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

• App 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 在此处很有用，因为同一个通道模型可以携带一个阶段性发布、支持回滚和显示更新活动的工作流。保持规则集小。短的政策比在事故期间建立的异常堆栈更容易审计。

如果您需要 API-基于的检查， Capgo 公共 API 文档 描述了设备、通道和包的资源。使用它来比较服务器视图与应用程序报告的内容。这种比较可以揭示过时的仪表板过滤器或由自动化创建的设备分配。

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

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

目标是停止将“未更新”视为一个失败。分析可以显示设备是否从未检查过，找不到符合条件的包，下载过程中失败，还是后来回滚了。

首先从受影响的设备组开始。根据应用程序版本、平台、频道和包版本进行过滤。寻找模式。如果只有一个旧应用程序构建失败，问题可能是本机兼容性门槛。如果一个频道中的所有设备都失败，检查频道或部署。

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

使用时间戳时要小心。仪表盘事件时间可能与用户的本地时间不同。将更新事件与设备的最后一次检查时间匹配。这在测试者说更新失败之前应用程序实际上还没有检查时有所帮助。

分析还可以帮助您安全地测试频道更改。一次更改一个变量。保持包版本不变，同时测试路由。然后保持路由不变，同时测试新包。如果同时更改两个变量，数据就无法告诉您哪个更改解决了问题。

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

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

Capgo的实时视图在CI/CD发布过程中最有用。部署任务可以上传一个包，监控步骤可以检查测试设备是否报告了预期的渠道和包。这样就把手动抱怨转化成了发布门槛。

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

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

第7步：防止默认渠道过时

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

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

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

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

保持本地频道code在明确的特性标志后面。测试助手调用时setChannel()确保生产版本不能意外包含它。请记住，缓存可能不会显示在仪表板中，因此UI无法捕捉到每个问题。

使用以下发布清单:

1. 确认应用ID和原生版本。
2. 选择目标频道。
3. 将捆绑包上传到该频道。
4. 确认捆绑包处于活动状态。
5. 运行设备烟雾测试。
6. 检查返回的频道与getChannel().
7. 在广泛推广之前，监控采用率。

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

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

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

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

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

FAQ

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

为什么 __CAPGO_KEEP_0__ 云默认通道无法更新现有设备？getChannel()现有设备可能会保留其旧通道直到下一次更新检查。局部通道、仪表板覆盖或强制赋值也可能优先于 Cloud Default。确认设备的解析通道，清除任何更强的赋值，然后将应用程序置于前台。

更改 Capgo 云默认会更改每个安装的应用吗？

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

npx cap sync对Capgo频道变化会做些什么?

npx cap sync将更新的Capacitor配置复制到原生项目中。如果您改变defaultChannel但跳过同步，下一次原生构建可能仍包含旧频道设置。从项目根目录运行命令，然后构建并安装一个新的测试二进制文件。

setChannel会在Capgo中创建一个设备覆盖吗?

No,setChannel()改变了本地存储的频道。它不会创建一个后端的设备覆盖，因此Capgo控制台可能不会显示设备被覆盖。清除本地赋值时设备应该返回到默认路由，然后使用getChannel().

Capgo可以通过OTA包更新原生code吗?

No,Capgo的OTA更新适用于Web层code，例如JavaScript、CSS和资产。原生插件、权限或原生API的更改需要一个新的商店构建。如果包期望原生code，而安装的应用程序缺乏，更新可能会被拒绝，即使频道是正确的。

结论

从解决的频道开始，而不是控制台默认值。检查 assignments，运行npx cap sync,验证包与原生运行时的兼容性，并检查设备日志，然后改变发布规则。然后在Capgo中添加一个小的后部署测试，调用getChannel()和确认预期的捆绑包。