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

常见更新问题

GitHub

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

先阅读

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

标题为“provider_infrastructure_request_blocked”

标题为“常见失败代码”

provider_infrastructure_request_blocked

标题为“先阅读”

原因

应用程序已 阻止供应商基础设施请求 启用，并且请求来自已知的Google或Apple数据中心IP范围。Capgo在 /updates, /stats,并 /channel_self 防止供应商起源的流量被视为设备流量。

解决方案

  • 从物理设备在正常用户网络上重现更新。
  • 在启用此保护时，不要使用云托管探针或供应商数据中心运行器进行更新、统计或通道自我检查。
  • 如果该流量是有意的，请打开应用程序的 信息 选项卡并关闭 阻止提供商基础设施请求重新启用它，当测试完成时。

新应用程序默认启用此保护。创建此设置之前的应用程序将其禁用，直到您启用它。

响应详细信息

  • /updates 保留更新器响应契约并返回 HTTP 200. 其体中包括 error, message, kind: "blocked". 或 provider ("google" 或 "apple").
  • /stats 和 /channel_self 返回 HTTP 429 with the same error code. Treat this as an intentional policy block, not a transient retry condition.

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).
  • 如果目标是 10.0.1, 基线大版本必须是 10 例如 10.0.0).

修复选项 A（推荐）：对齐设备基线大版本

设置 plugins.CapacitorUpdater.version 在 capacitor.config.* 所以它的 MAJOR 与您要交付的包 MAJOR 匹配（例如 1.0.0 为 1.0.1, 10.0.0 为 10.0.1).

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

  1. 运行 npx cap sync.
  2. 重建并重新安装本机应用程序。

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

允许跨主版本的自动更新（仅在该发布策略是有意的时才允许）。

相关文档：

disable_auto_update_to_minor / disable_auto_update_to_patch

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

原因

渠道策略更严格（minor 或 patch比所提供的更新更高版本。

  • minor 阻塞时，目标包的主版本或次版本与设备本地基线不同（version_build）。示例： 1.2.3 -> 1.3.0 被阻止。
  • patch 阻止任何主版本、次版本或补丁号的更改， version_build。仅允许后缀更改，同时 MAJOR.MINOR.PATCH 保持相同，例如 1.0.0-beta.1 -> 1.0.0-beta.2 或 1.0.0+build.1 -> 1.0.0+build.2.

context

  • HTML 文本片段来自更长的 Capgo UI 字符串（父键 `alternatives_cta_questions`）。页面/区域：Capacitor 实时更新替代方案比较页面。角色：长期营销或法律段落。见于：页面 alternatives.astro。保留 Capgo 产品/品牌和开发人员术语完全不变。消息键 `alternatives_cta_questions`（替代方案 CTA 问题）。| HTML 文本片段来自更长的 Capgo UI 字符串（父键 `appflow_cta_questions`）。页面/区域：Appflow 比较/迁移营销复制。角色：长期营销或法律段落。见于：页面 ionic-appflow.astro。保留 Capgo 产品/品牌和开发人员术语完全不变。消息键 `appflow_cta_questions`（Appflow CTA 问题）。| HTML 文本片段来自更长的 Capgo UI 字符串（父键 `capwesome_cta_questions`）。页面/区域：Capawesome 比较页面。角色：长期营销或法律段落。见于：页面 capwesome.astro。保留 Capgo 产品/品牌和开发人员术语完全不变。消息键 `capwesome_cta_questions`（Capwesome CTA 问题）。| HTML 文本片段来自更长的 Capgo UI 字符串（父键 `consulting_faq_subtitle`）。页面/区域：咨询服务页面。角色：小型 UI 标签或导航项。见于：页面 consulting.astro，页面 ionic-appflow.astro，页面 solutions/ionic-enterprise-plugins.astro。消息键 `appflow_plugins_or`（Appflow 或插件）。
  • change channel policy in dashboard/CLI.

上传与当前策略兼容的包，或者在控制台中__CAPGO_KEEP_0__更改频道策略。

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.

修复

  • 设置 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

Section titled “key_id_mismatch”

原因

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

解决方法

  • 确保应用程序配置和包加密流程中使用相同的加密密钥/公钥。

no_channel / null_channel_data

Section titled “no_channel / null_channel_data”

原因

设备上未找到有效的渠道。

解决方法

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

相关文档：

on_premise_app

context

Capgo发布渠道功能名称。页面/区域：Capgo解决方案营销页面。角色：短UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`solutions_white_label_visual_cell2_value`（解决方案白标签视觉单元2值）。

“本地应用”部分 on_premise_app原因

  1. App ID does not exist in Capgo 。这种情况发生在三个情况下： app_id 应用ID不存在于__CAPGO_KEEP_0__
  2. ——设备发送的 — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
  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_KEEP_0__/__CAPGO_KEEP_1__-updater 为@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updater中的本机能力 Using @capgo/capacitor-updater for the native capability in Using @capgo/capacitor-updater, Capgo for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, 添加或更新插件 添加或更新插件的实现细节，以及 Ionic 企业插件替代方案 查看产品工作流程