常见更新问题

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

先阅读

• no_new_version_available 这是一个正常状态，而不是失败状态。
• 许多“更新发现但未应用”的报告是政策/配置拒绝，而不是缓存延迟，尤其是当响应包含明确的 error code.
• Use npx @capgo/cli@latest app debug 常见失败代码

标题：常见失败代码

provider_infrastructure_request_blocked

标题：使用

应用有问题 阻止提供商基础设施请求 已启用，且请求来自已知的Google或Apple数据中心IP范围。 Capgo 在 /updates, /stats, /channel_self 中阻止这些请求，

Fix

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

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

响应详细信息

• /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（推荐）：使设备 baseline major 与您要发布的包 MAJOR 匹配（例如)

设置 plugins.CapacitorUpdater.version 在 capacitor.config.* 所以它的 主要版本 与您要发布的包 MAJOR 匹配（例如) 1.0.0 for 1.0.1, 10.0.0 for 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 or 1.0.0+build.1 -> 1.0.0+build.2.

修复

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

相关文档：

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

disable_auto_update_to_metadata

原因

Causeversion_numberChannel使用基于元数据的目标（ min_update_version.

Fix

• FixCapacitorUpdater.version将设备基线（
• adjust 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 ——设备发送的__CAPGO_KEEP_0__未注册，后端无法记录。
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 and read backend error code.

并阅读后端错误__CAPGO_KEEP_0__。

• 解决方案
• 如何获取支持

继续解决常见更新问题

如果您正在使用 使用@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updater 为@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updater中的本机能力 使用@capgo/capacitor-更新器 为使用@capgo/capacitor-updater的原生能力 Capgo由__CAPGO_KEEP_1__提供的插件 Capgo由__CAPGO_KEEP_1__提供的插件 Capacitor 由 Capgo 提供的插件 为 Capacitor 的实现细节在 Capgo 插件中。 添加或更新插件 为添加或更新插件的实现细节， Ionic 企业插件替代品 为 Ionic 企业插件替代品的产品工作流程。