常见更新问题

当更新检查失败时，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 与相同的错误 code. 将此视为故意的策略阻塞，而不是暂时的重试条件。

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：放宽渠道策略

在渠道设置中允许跨 MAJOR 自动更新 (仅当该发布策略是有意的)。

相关文档：

• 版本目标化：禁用跨主版本的自动更新
• 频道：禁用自动更新策略

disable_auto_update_to_minor / disable_auto_update_to_patch

原因

频道策略比更新的策略更严格（或）minor 阻止目标包有不同的主版本或次要版本而设备本地基线（） patch示例：

• minor 被阻止version_build阻止任何主版本、次要版本或补丁号的变化从 1.2.3 -> 1.3.0 只有后缀变化允许
• patch blocks when the target bundle has a different major or minor than the device native baseline ( version_buildis blocked. 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

原因

设备基线版本缺失 (unknown) 或无效 修复.

设置

• 为有效的 plugins.CapacitorUpdater.version 例如 同步并重建原生应用。 相关文档： 1.2.3.
• 频道：

频道版本控制和频道

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

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

Section titled “生产环境构建/开发环境构建/设备构建/模拟器构建”

Section titled “disable_prod_build / disable_dev_build / disable_device / disable_emulator”

原因

• 当前渠道或运行时目标不被允许。allow_prod, allow_dev, allow_device, allow_emulator解决方案

key_id_mismatch

Section titled “key_id_mismatch”

Section titled “密钥ID不匹配”

原因

• 应用程序配置和包装加密流程中的设备密钥与包装加密密钥不符。

no_channel / null_channel_data

原因

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

修复

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

渠道

• 标题为“on_premise_app”的部分

on_premise_app

后端返回HTTP 429

Section titled “on_premise_app” on_premise_app. 这三种情况下都会发生：

1. 在 Capgo 中未找到 App ID — 设备发送的 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 与注册的 ID 不符，或者输入了错误的 App ID。后端无法区分“未知 App”和“本地部署 App”，因此返回相同的错误 __CAPGO_KEEP_1__。

texts plugins.CapacitorUpdater.appId protectedTokens 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。

需要更多帮助吗?

• 获取支持的方法
• 从常见更新问题中继续

Section titled “从常见更新问题中继续”

If you are using 常见更新问题 为了计划原生插件工作，连接它 使用@capgo/capacitor-updater 在使用@capgo/capacitor-updater时，原生能力 Capgo插件目录 在Capgo插件目录中，产品工作流程 Capacitor插件由Capgo 在Capacitor插件由Capgo中，实现细节 添加或更新插件 添加或更新插件的实现细节 Ionic企业插件替代方案 在Ionic企业插件替代方案中，产品工作流程