常见更新问题

当更新检查失败时，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 with old: 0.0.0 表示设备报告基线 0.0.0,所以主要升级会被拒绝。

如何解释它

后端使用设备基线和目标比较主版本 old 和目标 version.

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

__CAPGO_KEEP_0__

确保 plugins.CapacitorUpdater.version 在 capacitor.config.* 这样 版本 与 1.0.0 您 1.0.1, 10.0.0 想要 10.0.1).

发布的

1. 包 npx cap sync.
2. 版本

匹配

然后将此配置应用到已安装的应用程序：

相关文档：

• 版本目标：禁用重大版本之间的自动更新
• 频道：禁用自动更新策略

disable_auto_update_to_minor / disable_auto_update_to_patch

原因

频道策略比（或）更新更严格（minor 当目标捆绑包的主要或次要版本与设备本机基线不同（ patch示例：

• minor 被阻止。version_build阻止任何主要、次要或补丁版本号的变化。 1.2.3 -> 1.3.0 阻止任何主要、次要或补丁版本号的变化。
• patch Channel policy is stricter (" or ") than the update being offered. version_build. Only suffix changes are allowed while 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.

修复

• Align device baseline (CapacitorUpdater.version) with installed native app version, or
• adjust min_update_version 相关文档：

Related docs:

• 标题：disable_auto_update_under_native

disable_auto_update_under_native

Cause

修复

上传一个大于或等于原生基线的包版本，或者

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

相关文档：

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

cannot_update_via_private_channel

原因

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

解决方案

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

相关文档：

• 频道：从您的应用程序中使用setChannel()

unknown_version_build / semver_error

原因

__CAPGO_KEEP_0__版本号不存在或无效unknown__CAPGO_KEEP_0__ 修复.

设置为

• 一个 plugins.CapacitorUpdater.version Sync and rebuild native app. 相关文档： 频道： 1.2.3.
• Bundle Versioning and Channels

修复

• 设置为
• Troubleshooting: 更新未应用

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

应用程序配置和捆绑加密流程中的设备密钥和捆绑加密密钥不一致。

解决

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

• Section titled “disable_prod_build / disable_dev_build / disable_device / disable_emulator”

no_channel / null_channel_data

原因

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

修复

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

通道

• Section titled “本地应用”

on_premise_app

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

后端返回 HTTP 429 on_premise_app 这种情况有三个:

1. 应用 ID 在 Capgo 中不存在 — 设备发送的 app_id 未注册，后端无法记录
2. 应用标记为本地部署 — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
3. 所以 __CAPGO_KEEP_0__ 云端点拒绝服务 组织计划已取消

— 应用的组织不再有有效订阅

常见错误 plugins.CapacitorUpdater.appId 在 ( capacitor.config.ts或与在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. Run npx @capgo/cli@latest app debug 并读取后端错误 code。

需要更多帮助吗？

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

从常见更新问题中继续

如果您正在使用 常见更新问题 为了规划原生插件工作，连接它与 使用@capgo/capacitor-updater 在使用@capgo/capacitor-updater中， Capgo插件目录 在Capgo插件目录中， Capacitor由Capgo 在Capacitor由Capgo中， 添加或更新插件 在添加或更新插件中， Ionic企业插件替代方案 了解Ionic企业版插件替代方案的产品工作流。