常见更新问题

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

先阅读此内容

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

常见故障代码

provider_infrastructure_request_blocked

原因

应用程序已 阻止供应商基础设施请求 Capgo在 /updates, /stats和 /channel_self 阻止供应商发起的流量被当作设备流量处理.

修复

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

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

响应详细信息

• /updates 保留更新器响应契约并返回 HTTP 200其正文包括 error, message, kind: "blocked"，和 provider ("google" 或 "apple").
• /stats 返回 HTTP /channel_self 与相同的错误 __CAPGO_KEEP_0__。将此视为有意的策略阻塞，而不是暂时重试条件。 429 with the same error code. Treat this as an intentional policy block, not a transient retry condition.

disable_auto_update_to_major

您的频道阻止了主要升级（

Your channel blocks major upgrades (disable_auto_update = major__CAPGO_KEEP_0__

典型症状

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 主要版本

设置 plugins.CapacitorUpdater.version 在 capacitor.config.* 所以它 主要 与您要交付的捆绑包 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.

修复

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

相关文档：

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

disable_auto_update_to_metadata

原因

渠道使用基于元数据的目标（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

原因

设备基线版本缺失（（））或无效的 semverunknown修复 设置.

到一个

• 有效的 semver plugins.CapacitorUpdater.version 例如 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 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标题：“密钥 ID 不匹配”

key_id_mismatch

频道禁用了当前的平台。

加密密钥和设备密钥不同。

修复

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

no_channel / null_channel_data

原因

未为设备解析有效的通道。

修复

• 设置云端默认通道，或
• 在测试构建中设置，或 defaultChannel 为设备分配通道覆盖。
• 相关文档：

__CAPGO_KEEP_0__

• 频道

on_premise_app

原因

后端返回 HTTP 429 on_premise_app这三种情况会发生:

1. 应用 ID 在 Capgo 中不存在 — 设备发送的 ID 未注册，后端无法记录。 app_id 应用标记为本地应用
2. — 应用存在但配置为自主更新，因此 __CAPGO_KEEP_0__ 云端点拒绝服务。 — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
3. — 应用的组织已失去活跃订阅。 后端返回 HTTP 429

常见错误

在 plugins.CapacitorUpdater.appId (in capacitor.config.ts) or a mismatch with the app ID registered in the Capgo dashboard. The backend cannot distinguish “unknown app” from “on-premise app”, so it returns the same error code.

或与__CAPGO_KEEP_0__控制台中注册的应用ID不匹配。后端无法区分“未知应用”和“本地应用”，因此返回相同的错误__CAPGO_KEEP_1__。

• 修复 app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
• 确保与__CAPGO_KEEP_0__控制台中显示的内容完全匹配（大小写敏感）。 npx @capgo/cli@latest app add.
• 如果应用尚未注册，请运行 plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• 将自主更新端点设置为__CAPGO_KEEP_0__云URL以外的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 企业插件替代品的产品工作流程.