常见更新问题

当更新检查失败时，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 返回 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

• ，在Capacitor live-update替代方案比较页面中保留Capgo产品/品牌和开发者术语。| 在Appflow比较/迁移营销文案中保留Capgo产品/品牌和开发者术语。| 在Capawesome比较页面中保留Capgo产品/品牌和开发者术语。| 在咨询服务页面中保留Capgo产品/品牌和开发者术语。| 在Appflow比较/迁移营销文案中保留Capgo产品/品牌和开发者术语。
• change channel policy in dashboard/CLI.

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

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

disable_auto_update_to_metadata

原因

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

解决方案

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

相关文档：

• Channels: Disable Auto Update strategies

disable_auto_update_under_native

原因

Channel prevents downgrades below the native baseline.

解决方法

• Upload a bundle version greater than or equal to native baseline, or
• disable “under native” downgrade protection for that channel.

相关文档:

• Version Targeting: Auto-Downgrade Prevention

cannot_update_via_private_channel

Cause

解决方法

Version Targeting: Auto-Downgrade Prevention

• 使用一个支持自我赋值的不同频道，或
• 使频道公开 / 启用自我赋值。

相关文档：

• 频道：从您的应用程序使用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 在测试构建中，或
• 为设备分配渠道覆盖

相关文档：

• 渠道

on_premise_app

本地应用

原因 on_premise_app后端返回HTTP 429

1. App ID does not exist in Capgo 应用ID不存在于__CAPGO_KEEP_0__ app_id ——设备发送的
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/capacitor-updater for the native capability in Using @capgo/capacitor-updater, Capgo插件目录 Capgo插件目录 Capacitor Capgo 为 Capacitor Capgo 的实现细节 添加或更新插件 为添加或更新插件, 和 Ionic 企业插件替代方案 为 Ionic 企业插件替代方案 的产品工作流