常见更新问题

当检查更新失败时，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 以防止来自服务商的流量被误判为设备流量。

修复

• 在普通用户网络环境下，使用真机复现更新过程。
• 在此保护功能启用期间，请勿使用云端探测器或服务商数据中心运行器进行 updater、stats 或 channel-self 检查。
• 如果该流量是预期的，请打开应用的 信息 选项卡并关闭 拦截了提供商的基础设施请求。测试完成后请重新开启。

新应用默认启用此保护。在此设置引入前创建的应用将保持禁用状态，直到你手动开启。

响应详情

• /updates 保持 updater 响应契约并返回 HTTP 200。其正文包含 error, message, kind: "blocked"，以及 provider ("google" 或 "apple").
• /stats 以及 /channel_self 返回 HTTP 429 并带有相同的错误 code。请将其视为预期的策略拦截，而非临时的重试条件。

disable_auto_update_to_major

原因

您的 Channel 拦截了主版本升级 (disable_auto_update = major)，且目标 Bundle 的主版本高于设备的基准版本。

典型症状

version: 1.0.8 配合 old: 0.0.0 表示设备报告的基础版本为 0.0.0，因此拒绝了重大版本升级。

如何解读该错误

后端会根据设备 baseline old 与目标版本进行比较 version.

• 如果目标版本是 1.0.1，则 baseline 的主版本号必须为 1 （例如 1.0.0).
• 如果目标版本是 10.0.1，则 baseline 的主版本号必须为 10 （例如 10.0.0).

解决方案 A（推荐）：对齐设备 baseline 的主版本号

设置 plugins.CapacitorUpdater.version 中的 capacitor.config.* 也就是说 主版本号 (MAJOR) 必须与你想要发布的 bundle MAJOR 版本一致（例如 1.0.0 用于 1.0.1, 10.0.0 用于 10.0.1).

然后对已安装的应用执行一次此配置：

1. 运行 npx cap sync.
2. 重新构建并重新安装 Native Build 应用。

修复方案 B：放宽 Channel 策略

在 Channel 设置中允许跨主版本自动更新（仅当你确实需要该发布策略时）。

相关文档：

• 版本目标控制：禁用跨大版本自动更新
• Channels：禁用自动更新策略

disable_auto_update_to_minor / disable_auto_update_to_patch

原因

Channel 策略比当前提供的更新策略更严格 (minor 或 patch)。

• minor 当目标 bundle 的大版本或次版本与设备 Native Build 基准不一致时，会拦截 (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.

修复

• 上传与当前策略兼容的 bundle，或者
• 在 dashboard/CLI 中更改 channel 策略。

相关文档：

• Channels: 禁用 Auto Update 策略

disable_auto_update_to_metadata

原因

Channel 使用基于 metadata 的定向机制 (version_number) 且设备的 baseline 低于要求 min_update_version.

修复

• 使设备基准 (CapacitorUpdater.version) 与已安装的 Native Build 版本一致，或
• 调整 min_update_version / channel 策略。

相关文档：

• Channels: 禁用 Auto Update 策略

disable_auto_update_under_native

原因

Channel 会防止版本降级至低于 Native Build 的基准版本。

修复

• 上传一个大于或等于 Native Build 基准版本的 bundle，或
• 为该 channel 禁用 “under native” 版本降级保护。

相关文档：

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

cannot_update_via_private_channel

原因

所选/默认 channel 不允许设备自分配。

解决方案

• 使用已启用自分配功能的其他 channel，或者
• 将该 channel 设置为公开 / 启用自分配。

相关文档：

• Channels：在 App 中使用 setChannel()

unknown_version_build / semver_error

原因

设备基准版本缺失 (unknown) 或 无效的 semver.

修复方法

• 设置 plugins.CapacitorUpdater.version 至 无效的 semver 例如 1.2.3.
• 同步并重新构建 Native Build。

相关文档：

• 频道：Bundle 版本管理与频道
• 故障排除：更新未生效

unsupported_plugin_version

原因

Updater 插件版本过低，无法满足当前后端要求。

修复方案

• 升级 @capgo/capacitor-updater.
• 运行 npx cap sync.
• 重新构建并重新安装 Native Build 应用。

disabled_platform_ios / disabled_platform_android

原因

该 Channel 已禁用该平台的更新功能。

修复方案

• 在 Channel 中开启平台开关。

disable_prod_build / disable_dev_build / disable_device / disable_emulator

原因

Channel 不允许当前的 Build 类型或运行时目标。

解决方案

• 调整 Channel 配置 (allow_prod, allow_dev, allow_device, allow_emulator) 以匹配您的测试目标。

key_id_mismatch

原因

Bundle 加密密钥与设备密钥不一致。

解决方案

• 请确保 App 配置与 Bundle 加密流程中使用相同的加密密钥/公钥。

no_channel / null_channel_data

原因

未为该设备解析到有效的 channel。

解决方案

• 设置云端默认 channel，或者
• 设置 defaultChannel 在测试构建中，或者
• 为设备分配 channel override。

相关文档：

• 通道

on_premise_app

原因

后端返回 HTTP 429 错误： on_premise_app这通常由以下三种情况引起：

1. Capgo 中不存在该 App ID — 设备发送的 app_id 未注册，因此后端没有相关记录。
2. App 被标记为本地部署 (on-premise) — App 虽然存在，但配置为自托管更新，因此 Capgo 云端接口拒绝提供服务。
3. 组织方案已取消 — 该 App 所属组织的订阅已失效。

常见错误

拼写错误 plugins.CapacitorUpdater.appId (在 capacitor.config.ts) 或与 Capgo dashboard 中注册的 App ID 不匹配。由于后端无法区分“未知 App”与“私有化部署 App”，因此会返回相同的错误 code。

解决方案

• 请核实 app_id 是否与 Capgo dashboard 中显示的内容完全一致（区分大小写）。
• 如果 App 尚未注册，请运行 npx @capgo/cli@latest app add.
• 如果 App 确定为私有化部署，请将 plugins.CapacitorUpdater.updateUrl 设置为您的自托管更新端点，而非 Capgo 云端 URL。
• 如果 Organization 方案已过期，请续费或升级方案。

快速排查清单

1. 确认该 Build 对应的 App ID 和 Channel 是否正确。
2. 确认 CapacitorUpdater.version 与已安装的 Native Build 版本匹配。
3. 确认 Channel 策略 (disable_auto_update) 与预期的发布计划一致。
4. 确认平台/构建目标开关允许该设备。
5. 运行 npx @capgo/cli@latest app debug 并阅读后端错误 code。

需要更多帮助？

• 故障排除
• 如何获取支持

继续阅读常见更新问题

如果你正在使用 常见更新问题 要规划原生插件工作，请将其与 使用 @capgo/capacitor-updater 在“使用 @capgo/capacitor-updater”中用于原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。