常见更新问题

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

先读这个

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

常见错误代码

disable_auto_update_to_major

原因

您的频道阻止了主要升级（disable_auto_update = major）并且目标包的主要版本号高于设备基线版本。

典型症状

version: 1.0.8 表示设备报告基线 old: 0.0.0 ，因此拒绝了主要升级。 0.0.0如何解释它

with

后端使用设备基线和目标进行主要版本比较 old 如果目标是 version.

• ,基线主要版本必须是 1.0.1(例如 1 如果目标是 1.0.0).
• ,基线主要版本必须是 10.0.1(例如 10 修复选项 A（推荐）：将设备基线主要版本与目标对齐 10.0.0).

设置

在 plugins.CapacitorUpdater.version 以此方式 capacitor.config.* so its 重大版本 __CAPGO_KEEP_0__符合您要发布的捆绑包的重大版本（例如 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）

解决方案

• 上传一个与当前策略兼容的捆绑包，或者
• 在控制台中更改渠道策略（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

原因

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

修复

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

相关文档：

• Channels: 在应用中使用 setChannel()

unknown_version_build / semver_error

原因

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

设置

• 到一个有效的 semver，如 plugins.CapacitorUpdater.version 同步并重建原生应用。 1.2.3.
• 相关文档：

Channels: Bundle Versioning and Channels

• 故障排除：更新未应用
• 故障排除：更新未应用

unsupported_plugin_version

原因

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

修复

• 升级 @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

应用配置和捆绑加密流程中的设备密钥和捆绑加密密钥不相同。

解决方案

在应用配置和捆绑加密流程中使用相同的加密密钥/公共密钥。

• 无渠道 / null_channel_data

no_channel / null_channel_data

原因

未能为设备解析有效的渠道。

修复

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

渠道

• 标题为“on_premise_app”的部分

on_premise_app

后端返回HTTP 429

Related docs: __CAPGO_KEEP_0__ on_premise_app. 这三种情况下都会发生：

1. 在 Capgo 中未找到 App ID — 设备发送的信息未注册，后端因此无法找到它的记录。 app_id App 被标记为本地部署
2. — App 存在，但配置为自主更新，因此 __CAPGO_KEEP_0__ 云端点拒绝为其服务。 — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
3. — App 的组织已失去活跃订阅。 常见错误

在 __CAPGO_KEEP_0__ 中的 App ID 中出现了拼写错误，或者与注册在 __CAPGO_KEEP_0__ 控制台中的 App ID 不符。后端无法区分“未知 App”和“本地部署 App”，因此返回相同的错误 __CAPGO_KEEP_1__.

texts plugins.CapacitorUpdater.appId App ID 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.

修复

• 确认 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。

需要更多帮助吗?

• 故障排除
• 获取支持的方法