跳过内容
Capgo - 为 Capacitor 应用程序提供实时更新 Capgo

常见更新问题

当更新检查失败时，Capgo通常返回一个 error code和一个 message 在 /updates 响应中。这一页解释了最常见的失败和最快的修复方法。

请先阅读

标题：请先阅读
  • no_new_version_available 是正常状态，而不是失败状态。
  • 许多“更新发现但未应用”的报告实际上是拒绝了策略/配置，而不是缓存延迟，尤其是当响应包含明确的 error code.
  • 使用 npx @capgo/cli@latest app debug 在复制问题时查看请求/响应详细信息。

常见故障代码

标题：常见故障代码

disable_auto_update_to_major

标题：disable_auto_update_to_major

原因

您的频道阻止了主要升级（disable_auto_update = major和目标包的主版本号高于设备基线版本号。

典型症状

version: 1.0.8 表示设备报告基线 old: 0.0.0 ,所以主版本升级会被拒绝。 0.0.0如何解释

后端使用设备基线和目标版本号比较主版本号。

和目标 old 如果目标是 version.

  • ,基线主版本号必须是 1.0.1(例如 1 如果目标是 1.0.0).
  • __CAPGO_KEEP_0__ 10.0.1baseline 主要版本必须 10 (例如 10.0.0).

修复选项 A (推荐): 对齐设备 baseline 主要

设置 plugins.CapacitorUpdater.version 在 capacitor.config.* 这样 MAJOR 匹配您要交付的捆绑 MAJOR (例如 1.0.0 对于 1.0.1, 10.0.0 对于 10.0.1).

然后将此配置应用到安装的应用程序：

  1. Run npx cap sync.
  2. 重新构建并重新安装原生应用。

修复选项 B：放宽渠道策略

允许在渠道设置中跨主要版本自动更新（仅当该发布策略是有意的）。

相关文档：

disable_auto_update_to_minor / disable_auto_update_to_patch

标题：禁用到次要版本的自动更新 / 禁用到补丁版本的自动更新

原因

渠道策略比更新的策略更严格（或）minor 修复 patch__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

  • 上传一个与当前策略兼容的捆绑包，或者
  • 在控制台中CLI修改频道策略。

相关文档：

disable_auto_update_to_metadata

标题：disable_auto_update_to_metadata

原因

频道使用基于元数据的目标（version_number）并且设备基线低于所需 min_update_version.

修复

  • 将设备基线（CapacitorUpdater.version）与安装的原生应用程序版本对齐，或者
  • 调整 min_update_version / 渠道策略。

相关文档：

disable_auto_update_under_native

标题："disable_auto_update_under_native"

原因

渠道防止降级到原生基线以下。

修复

  • 上传一个版本大于或等于原生基线的捆绑包，或者
  • 禁用 "在原生" 下降级保护该渠道。

相关文档：

cannot_update_via_private_channel

标题："cannot_update_via_private_channel"

原因

已选择/默认的频道不允许设备自行分配。

修复

  • 使用一个支持自行分配的频道，或
  • 将频道设置为公共 / 开启自行分配。

相关文档：

unknown_version_build / semver_error

标题为“未知版本构建 / semver 错误”

原因

设备基线版本缺失（）或unknown无效的 semver __CAPGO_KEEP_0__.

修复

  • 设置 plugins.CapacitorUpdater.version 到一个 有效的semver 例如 1.2.3.
  • 同步并重建原生应用。

相关文档：

unsupported_plugin_version

标题为“不支持的插件版本”

原因

更新插件版本太旧，无法满足当前后端要求。

修复

  • 升级 @capgo/capacitor-updater.
  • 运行 npx cap sync.
  • 重建并重新安装原生应用。

disabled_platform_ios / disabled_platform_android

标题： “disabled_platform_ios / disabled_platform_android”

原因

该频道已禁用该平台的更新。

修复

  • 在频道中启用平台切换。

disable_prod_build / disable_dev_build / disable_device / disable_emulator

标题： “disable_prod_build / disable_dev_build / disable_device / disable_emulator”

原因

频道禁止当前的构建类型或运行时目标。

修复

  • 使（）选项与测试目标对齐.allow_prod, allow_dev, allow_device, allow_emulator标题：key_id_mismatch

key_id_mismatch

原因

应用配置和包加密流程中使用的加密密钥/公钥不一致.

修复

在应用配置和包加密流程中使用相同的加密密钥/公钥.

  • 标题：no_channel / null_channel_data

no_channel / null_channel_data

原因

设备上未找到有效的通道.

修复

Fix

  • 设置一个云端的默认频道，或
  • 设置 defaultChannel 在测试构建中，或
  • 为设备分配频道覆盖

相关文档：

on_premise_app

标题为“on_premise_app”

原因

后端返回 HTTP 429 on_premise_app. 这种情况有三个：

  1. App ID 在 Capgo 中不存在 — app_id 该设备发送的信息未注册，因此后端无法找到它的记录。
  2. 应用程序被标记为本地部署 — 应用程序存在但配置为自主更新，因此Capgo云端点拒绝为其服务。
  3. 组织计划已取消 — 应用程序的组织不再具有有效的订阅。

常见错误

输入错误 plugins.CapacitorUpdater.appId （在 capacitor.config.ts）或应用程序ID与Capgo控制台中注册的ID不匹配。后端无法区分“未知应用程序”和“本地部署应用程序”，因此返回相同的错误code。

修复

  • 验证 app_id 确保它与Capgo控制台中显示的内容完全匹配（大小写敏感）。
  • 如果应用程序尚未注册，请运行 npx @capgo/cli@latest app add.
  • 如果应用程序是意图在本地环境中运行的，请设置 plugins.CapacitorUpdater.updateUrl 到您的自托管更新端点而不是Capgo云URL.
  • 如果组织计划已过期，请续费或升级计划.

快速诊断清单

快速诊断清单
  1. 确认应用程序ID和渠道与构建正确匹配.
  2. 确认 CapacitorUpdater.version 与安装的本机应用程序版本匹配.
  3. 确认渠道策略（disable_auto_update）与预期的发布一致.
  4. 确认平台/构建目标开关允许此设备.
  5. 运行 npx @capgo/cli@latest app debug 并阅读后端错误 code。

需要更多帮助？

标题：需要更多帮助？

继续从常见更新问题

标题：继续从常见更新问题

如果您正在使用 常见更新问题 来规划原生插件工作，连接它与 使用 @capgo/capacitor-updater 为原生能力在使用 @capgo/capacitor-updater 中 Capgo 插件目录 为产品工作流程在 Capgo 插件目录中 Capacitor 插件由 Capgo 为实现细节在 Capacitor 插件由 Capgo 中 添加或更新插件 为实现细节在添加或更新插件中 Ionic 企业插件替代方案 为产品工作流程在 Ionic 企业插件替代方案中