常见更新问题
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
当更新检查失败时,Capgo 通常会返回一个 error code 和一个 message ,详见 /updates 响应。本页介绍最常见的失败情况和最快的修复方法。
请先阅读
标题为“请先阅读”的章节no_new_version_available属于正常状态,并非失败。- 许多“发现更新但未应用”的报告其实是策略/配置拒绝,而不是缓存延迟,尤其是当响应中包含明确的
errorcode。 - 使用
npx @capgo/cli@latest app debug复现问题时查看请求/响应详情。
常见失败代码
标题为“常见失败代码”的章节provider_infrastructure_request_blocked
标题为“provider_infrastructure_request_blocked”的章节原因
应用已启用 拦截提供商基础设施请求 功能,且请求源自已知的 Google 或 Apple 数据中心 IP 段。Capgo 会在 /updates, /stats,以及 /channel_self 以防止来自服务商的流量被误判为设备流量。
修复
- 请在普通用户网络环境下,使用真机复现更新过程。
- 启用此保护时,请勿使用云端探测器或服务商数据中心运行器进行 updater、stats 或 channel-self 检查。
- 如果该流量是预期的,请打开应用的 信息 选项卡并关闭 拦截提供商基础设施请求。测试完成后请重新开启。
新应用默认启用此保护。在引入该设置之前创建的应用将保持禁用状态,直到你手动开启。
响应详情
/updates保持了 updater 的响应契约并返回 HTTP200。其响应体包含error,message,kind: "blocked",以及provider("google"或"apple")./stats以及/channel_self返回 HTTP429,并附带相同的错误 code。请将其视为有意为之的策略拦截,而非可重试的瞬时故障。
disable_auto_update_to_major
标题为“disable_auto_update_to_major”的章节原因
您的渠道禁止主要版本升级(disable_auto_update = major),且目标 bundle 的主要版本号高于设备基线版本。
典型症状
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.* 因此,它 大版本 与您想要发布的 bundle MAJOR 版本匹配(例如 1.0.0 来实现 1.0.1, 10.0.0 来实现 10.0.1).
然后,将此配置一次性应用到已安装的应用:
- 运行
npx cap sync. - 重新构建并重新安装原生应用。
修复方案 B:放宽 channel 策略
在渠道设置中允许跨主版本自动更新(仅当该发布策略是有意为之时)。
相关文档:
disable_auto_update_to_minor / disable_auto_update_to_patch
章节标题:“disable_auto_update_to_minor / disable_auto_update_to_patch”原因
Channel 策略比正在提供的更新更严格(minor 或 patch)。
minor当目标 bundle 的主版本或次版本与设备原生基线不同时,会拦截(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 策略。
相关文档:
disable_auto_update_to_metadata
标题为“disable_auto_update_to_metadata”的章节原因
Channel 使用基于 metadata 的定向 (version_number) 且设备 baseline 低于要求的 min_update_version.
修复
- 将设备基线 (
CapacitorUpdater.version) 与已安装的原生应用版本对齐,或 - 调整
min_update_version/ channel 策略。
相关文档:
disable_auto_update_under_native
标题为 “disable_auto_update_under_native” 的章节原因
Channel 会阻止降级到原生基线以下。
修复
- 上传版本大于或等于原生基线的 bundle,或
- 禁用该频道的“低于原生版本”降级保护。
相关文档:
cannot_update_via_private_channel
标题为“cannot_update_via_private_channel”的章节原因
所选/默认频道不允许设备自行分配。
修复
- 使用启用了自行分配的其他频道,或者
- 将频道设为公开 / 启用自行分配。
相关文档:
unknown_version_build / semver_error
标题为“unknown_version_build / semver_error”的章节原因
设备基线版本缺失(unknown)或不是 有效的 semver.
修复
- 设置
plugins.CapacitorUpdater.version到 有效的 semver 例如1.2.3. - 同步并重新构建原生应用。
相关文档:
unsupported_plugin_version
标题为“unsupported_plugin_version”的章节原因
Updater 插件版本过旧,不满足当前后端要求。
修复
- 升级
@capgo/capacitor-updater. - 运行
npx cap sync. - 重新构建并重新安装原生应用。
disabled_platform_ios / disabled_platform_android
标题为“disabled_platform_ios / disabled_platform_android”的章节原因
该 Channel 已针对此平台禁用更新。
修复
- 在 Channel 中启用平台切换。
disable_prod_build / disable_dev_build / disable_device / disable_emulator
标题为 “disable_prod_build / disable_dev_build / disable_device / disable_emulator” 的章节原因
Channel 不允许当前的 build 类型或运行时目标。
修复
- 对齐 Channel 选项(
allow_prod,allow_dev,allow_device,allow_emulator)与您的测试目标。
key_id_mismatch
标题为 “key_id_mismatch” 的章节原因
Bundle 加密密钥与设备密钥不一致。
修复
- 在应用配置和 bundle 加密工作流中使用相同的加密密钥/公钥。
no_channel / null_channel_data
标题为 “no_channel / null_channel_data” 的章节原因
未能为该设备解析出有效的 channel。
修复
- 设置云端默认 channel,或者
- 设置
defaultChannel在测试构建中,或者 - 为设备分配 channel 覆盖。
相关文档:
on_premise_app
标题为 “on_premise_app” 的章节原因
后端返回 HTTP 429,并带有 on_premise_app这会在三种情况下发生:
- Capgo 中不存在该 App ID — 设备发送的
app_id未注册,因此后端没有相关记录。 - App 被标记为本地部署 (on-premise) — App 虽然存在,但配置为自托管更新,因此 Capgo 云端接口拒绝提供服务。
- 组织套餐已取消 — 该 App 所属组织的订阅已失效。
常见错误
拼写错误出现在 plugins.CapacitorUpdater.appId (在 capacitor.config.ts) 或与 Capgo 仪表板中注册的应用 ID 不匹配。后端无法区分“未知应用”和“本地部署应用”,因此会返回相同的错误 code。
修复
- 请检查
app_id与 Capgo 仪表板中显示的内容完全一致(区分大小写)。 - 如果应用尚未注册,请运行
npx @capgo/cli@latest app add. - 如果应用是有意进行本地部署的,请设置
plugins.CapacitorUpdater.updateUrl为您的自托管更新端点,而不是 Capgo 云 URL。 - 如果组织计划已过期,请续订或升级计划。
快速排查清单
标题为“快速诊断清单”的章节- 确认该构建的应用 ID 和通道是否正确。
- 确认
CapacitorUpdater.version与已安装的原生应用版本匹配。 - 确认频道策略 (
disable_auto_update) 与预期发布计划一致。 - 确认平台/构建目标开关已允许该设备。
- 运行
npx @capgo/cli@latest app debug并查看后端错误 code。
需要更多帮助?
标题为“需要更多帮助?”的章节继续阅读:常见更新问题
标题为“从常见更新问题继续”的章节如果你正在使用 常见更新问题 要规划原生插件工作,请将其与 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。