常见更新问题

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

先阅读

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

常见故障代码

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 和 429 使用相同的错误 code. 将其视为故意的策略阻塞，而不是暂时的重试条件。

disable_auto_update_to_major

Cause

您的频道阻止了主要升级（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.1baseline 主版本必须 10 例如 10.0.0).

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

Set 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

• 上传一个与当前策略兼容的捆绑包，或者
• change channel policy in dashboard/CLI.

上传与当前策略兼容的包，或者

• 在控制台中修改频道策略__CAPGO_KEEP_0__。

disable_auto_update_to_metadata

原因

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

解决方案

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

相关文档：

• 频道：禁用自动更新策略

disable_auto_update_under_native

原因

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

解决方案

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

相关文档：

• 版本目标：自动降级防止

cannot_update_via_private_channel

原因

选定的/默认渠道不允许设备自我分配。

解决方案

• 使用一个支持自我分配的不同渠道，或者
• 使频道公开 / 启用自我分配。

相关文档：

• 频道：从您的应用程序中使用 setChannel()

unknown_version_build / semver_error

原因

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

解决方案

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

相关文档：

• 频道：频道版本和频道
• 故障排除：更新未应用

unsupported_plugin_version

原因

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

修复

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

disabled_platform_ios / disabled_platform_android

原因

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

解决方案

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

disable_prod_build / disable_dev_build / disable_device / disable_emulator

原因

频道不允许当前的构建类型或运行目标。

解决方案

• 将频道选项（allow_prod, allow_dev, allow_device, allow_emulator）与您的测试目标对齐。

key_id_mismatch

问题原因

应用包加密密钥与设备密钥不一致。

解决方法

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

no_channel / null_channel_data

问题原因

未为设备分配有效渠道。

解决方法

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

相关文档：

• 频道

on_premise_app

Cause

原因 on_premise_app后端返回HTTP 429的

1. 应用 ID 在 Capgo 中不存在 — the app_id ——设备发送的
2. 未注册，因此后端没有记录。 — 应用程序存在，但配置为自主更新，因此Capgo云端点拒绝为其服务。
3. ——应用存在但配置为自主更新，因此__CAPGO_KEEP_0__云端点拒绝服务它。 — 应用程序的组织不再具有有效的订阅。

常见错误

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

修复

• 确认 app_id 确保与 Capgo 控制台中显示的 ID 匹配（区分大小写）。
• 如果应用程序尚未注册，请运行 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/capacitor-updater 为使用@capgo/capacitor-updater的原生能力 Capgo插件目录 Capgo由__CAPGO_KEEP_1__提供 Capacitor由Capgo提供 为 Capacitor 插件的实现细节提供了 Capgo 的支持。 添加或更新插件 为添加或更新插件的实现细节提供详细信息，并 Ionic 企业插件替代方案 为 Ionic 企业插件替代方案的产品工作流提供详细信息。