调试

理解云端日志

如果你遇到云端拒绝 code，并需要更深入的修复指南，请参阅 常见更新问题.

Capgo 日志可能包含事件的元数据。在 dashboard 中，按 snake_case 格式的 action code 筛选，然后点击 metadata 单元格即可复制完整的 JSON payload。元数据对 crash 和 WebView 事件特别有用，因为它可能包含错误消息、源 URL、行号和列号、进程状态、内存压力或平台特定原因。较旧的日志仍可能显示括号中列出的旧版 camelCase 别名。

每个章节标题都与控制台日志表中显示的 action code 一致，因此你可以直接链接到对应章节。

套餐限制与正常响应

与计费、限流或非错误状态相关的后端拒绝。

InvalidIp

含义

Capgo 检测到疑似来自 Google 或云基础设施的流量。发布不足四小时的更新会被忽略，这样 bot 流量就不会被计为计费设备。

处理方式

请忽略真实用户的此类情况。请尝试使用普通网络和真实设备重试，或稍后再次检查。

provider_infrastructure_request_blocked

含义

您的应用已配置为拦截来自 Google 和 Apple 已知数据中心 IP 段的请求。此保护机制适用于更新检查、统计数据和 channel-self 请求，因此即使应用配置有效，云端托管的探测器和 provider runner 也可能收到此响应。

处理方式

请使用处于普通用户网络下的物理设备进行重试。如果来自 provider 的流量是预期的，请暂时禁用 拦截 provider 基础设施请求 在 App 的 信息 选项卡，并在测试完成后重新启用。新应用默认开启此设置；现有应用将保留之前的禁用设置，直到手动更改。

needPlanUpgrade

含义

您的组织已达到套餐或设备限制。在升级套餐或下一个计费周期重置用量之前，设备将无法接收更新。

处理方式

请在 dashboard 中升级您的套餐，或等待下一个计费周期。

noNew

含义

该设备已拥有其 channel 的最新 bundle。这属于正常状态，并非错误。

rateLimited

含义

设备在短时间内发送了过多的 update 或 channel 请求。

处理方式

请停止在 render 循环中调用 update API。应仅在 setChannel / getChannel 用户操作时进行调用，并设置 defaultChannel 中的 capacitor.config.

版本格式

原生版本元数据无效导致的后端拒绝。

semver_error

含义

配置中的原生应用版本缺失或不是有效的 semver（x.y.z).

处理方式

设置 plugins.CapacitorUpdater.version 要转换为有效的 semver，请在以下位置验证 SemVer 测试器），然后重新构建并重新安装原生应用。

平台与构建目标

当频道策略拦截了特定平台、构建类型或设备类型时，后端会拒绝请求。

disablePlatformIos

含义

设备运行的是 iOS，但该频道已禁用 iOS 更新。

处理方式

如果这是误操作，请在频道中启用 iOS；如果是有意拦截，请将 iOS 构建路由到专用频道。

disablePlatformAndroid

含义

设备运行的是 Android，但该频道已禁用 Android 更新。

处理方式

如果这是误操作，请在该 channel 中启用 Android；如果是有意拦截，请将 Android build 路由到专用 channel。

disablePlatformElectron

含义

设备正在运行 Electron，但该 channel 已禁用 Electron 更新。

处理方式

如果这是误操作，请在该 channel 中启用 Electron；如果是有意拦截，请将 Electron build 路由到专用 channel。

disableDevBuild

含义

该设备是 dev build，但此 channel 已禁止 dev build。

处理方式

在测试 channel 中允许 dev build，或保持此 channel 仅用于 release，并将 dev 设备移到别处。

disableProdBuild

含义

名为以下名称的生产环境构建： /updates，但该频道已禁止生产环境更新。

处理方式

如果这是误操作，请在该频道中允许生产环境更新，或者将生产环境构建路由到正确的频道。

disableDevice

含义

由于该频道禁止真机使用，因此拦截了真实的手机或平板设备。

处理方式

如果这是误操作，请启用真机更新；否则请保留此限制，并将真机路由到其他频道。

disableEmulator

含义

当前设备为模拟器，但该 channel 已禁用模拟器更新。

处理方式

请在测试 channel 中启用模拟器更新，或保持当前 channel 禁用模拟器，并使用其他 channel 进行模拟器验证。

自动更新兼容性规则

当 semver 或元数据规则拦截目标 bundle 时，后端会拒绝请求。

disableAutoUpdate

含义

由于 channel 兼容性策略，已禁用 Auto-update。元数据包含 auto_update 并包含匹配的规则，例如 major, minor, patch, metadata，或 none.

处理方式

更改通道的自动更新策略，以支持你计划的发布方式。

disableAutoUpdateUnderNative

含义

该通道的 bundle 比设备基线版本旧，因此会阻止针对该原生版本的更新推送。

处理方式

发布一个不低于原生基线版本的 bundle，或者在通道中禁用 under-native 保护。

disableAutoUpdateMetadata

含义

该通道要求 min_update_version，但设备的原生版本低于该阈值。

处理方式

设置 min_update_version 针对来自更新版本 Native Build 的目标 bundle 或 release。

disableAutoUpdateToMajor

含义

该 channel 会拦截大版本跳跃，例如 1.x.x 改为 2.x.x.

处理方式

使 channel 策略与您的主要发布计划保持一致，或者允许该 track 进行大版本跳跃。请参阅 常见更新问题.

disableAutoUpdateToMinor

含义

该 channel 会拦截相对于设备 Native 基线的次版本跳跃（version_build），例如 1.2.3 改为 1.3.0.

处理方式

让频道策略与你的 minor 发布计划保持一致，或允许此轨道进行 minor 版本跳跃。

disableAutoUpdateToPatch

含义

该频道会阻止 patch 级别变更，同时保持相同 MAJOR.MINOR.PATCH 前缀；仅允许后缀变更。

处理方式

让发布节奏与频道策略保持一致，或允许此轨道进行 patch 跳跃。

Channel 配置

因频道配置缺失或不兼容导致的后端拒绝。

cannotUpdateViaPrivateChannel

含义

设备尝试自行关联到一个不允许设备自行分配的私有频道（allow_device_self_set is false）且该频道不是公开频道。

处理方式

启用 allow_device_self_set 在该频道上启用，或将设备切换到公开或允许的频道。

channelMisconfigured

含义

该频道使用了 disable_auto_update: "version_number" 但 bundle min_update_version 为 null，因此 Capgo 无法判断哪些设备应该更新。

处理方式

请为该规则补充缺失的配置，或切换到更简单的自动更新模式。

NoChannelOrOverride

含义

未配置默认 Channel，且设备未设置 Channel override。

处理方式

在 dashboard 中设置默认 Channel，或在 defaultChannel 构建中进行配置。

Bundle 传输与加密

当 Capgo 无法提供或解密 bundle 时，后端会拒绝请求。

cannotGetBundle

含义

Capgo 无法生成有效的签名下载 URL，且没有可用的 manifest 回退方案。

处理方式

请重新 upload bundle，重新生成 manifests，并检查 R2 或 public bundle 设置。

missingBundle

含义

分配给该 channel 的 bundle 没有可下载内容：没有 external_url，没有 r2_path，不是内置版本，且没有 manifest 条目。

处理方式

重新 build 并 re-upload 该版本，然后确认 bundle 包含实际文件内容。

keyMismatch

含义

设备加密公钥与用于加密 bundle 的密钥不匹配。元数据可能包含 device_key_id, bundle_key_id，以及 version.

处理方式

在控制台中对比设备与 bundle 的 key ID。请使用相同的密钥并确保 CLI/plugin 版本匹配。

App 配置与旧版客户端

由于 App 配置或不支持的 updater 版本导致的后端拒绝请求。

customIdBlocked

含义

App 发送了自定义设备 ID，但该 App 不接受自定义 ID，因此该 ID 已被忽略。

处理方式

停止发送自定义 ID，或者仅在工作流确实需要时才启用自定义 ID。

blocked_by_server_url

含义

server.url 已在 Capacitor 配置中设置，因此 WebView 会加载远程 URL 而非本地 bundle 文件。Capgo Live Updates 需要本地文件，且 server.url 不建议在生产环境中使用。

处理方式

移除或清除 server.url 以确保生产构建的更新负载保持在本地。此 code 可能表现为后端拒绝，也可能是设备端的统计。

backend_refusal

含义

updater plugin 版本为 v4，后端已不再接受该版本。

处理方式

将插件和 CLI 升级至 v5+（推荐 v8），并使用 Capacitor v5+，重新构建并重新发布 bundle 元数据。

Update 生命周期

涵盖正常更新流程、激活和回滚的设备端事件。

ping

含义

用于验证 stats pipeline 的内部测试操作。

get

含义

Capgo 已向设备发送新版本的下载信息。

set

含义

设备上已激活一个 bundle。

set_fail

含义

设备上的 bundle 激活失败。

处理方式

使用以下命令检查 native logs npx @capgo/cli@latest app debug 并验证 bundle 的完整性、路径以及 notifyAppReady 流程。

reset

含义

设备已重置回内置 bundle。

delete

含义

设备上已删除一个 bundle。

下载与安装失败

设备端关于下载进度、归档校验及安装错误的事件。

download_0

含义

下载序列已启动，进度为 0%。

download_10

含义

已下载新的 bundle —— 进度显示为 10%。

download_20

含义

已下载新 bundle — 进度显示为 20%。

download_30

含义

已下载新 bundle — 进度显示为 30%。

download_40

含义

已下载新 bundle — 进度显示为 40%。

download_50

含义

已下载新 bundle — 进度显示为 50%。

download_60

含义

已下载新的 bundle — 进度显示为 60%。

download_70

含义

已下载新的 bundle — 进度显示为 70%。

download_80

含义

已下载新的 bundle — 进度显示为 80%。

download_90

含义

已下载新的 bundle — 进度显示为 90%。

download_complete

含义

Bundle 下载成功。

download_manifest_start

含义

设备开始下载更新清单 (manifest)。

download_manifest_complete

含义

设备已完成更新清单下载。

download_zip_start

含义

设备开始下载 Bundle 压缩包。

download_zip_complete

含义

设备已完成 bundle 归档文件的下载。

download_manifest_file_fail

含义

其中一个 manifest 条目下载失败。 version_name 用于 version:fileName 来识别该资源。

处理方式

修复缺失或被拦截的资源，重新生成 manifest，然后重新 upload bundle。

download_manifest_checksum_fail

含义

manifest 文件的校验和 (checksum) 验证失败。

处理方式

使用当前的 CLI 版本重新上传 bundle，并校验 manifest checksum。

download_manifest_brotli_fail

含义

Manifest 文件 Brotli 解压失败。

处理方式

检查压缩设置并重新上传受影响的 assets。

download_fail

含义

Bundle 下载失败。

处理方式

检查网络连接、signed URL 是否过期、CDN 可达性以及设备存储空间。

update_fail

含义

Bundle 已安装，但应用从未调用 notifyAppReady，因此 Capgo 已回滚。

处理方式

调用 notifyAppReady() 在应用完成引导后。Native 日志文本 notifyAppReady was not called, roll back current bundle 对应此 code。

checksum_fail

含义

下载的 Bundle 校验和验证失败。常见原因：旧版 CLI 上传导致的 CRC32 与 SHA256 不匹配，或旧版插件因加密密钥不匹配将解密失败显示为校验和失败。

处理方式

使用当前的 CLI/plugin (SHA256) 重新上传。如果启用了加密，请确认 App 公钥与上传密钥匹配，或升级到 plugin 8.3.0+ 以获得明确的 keyMismatch 错误。

decrypt_fail

含义

下载的 bundle 解密失败。

处理方式

请验证加密密钥，并使用匹配的密钥对重新上传 bundle。

windows_path_fail

含义

zip 文件包含非法的 Windows 风格路径。

处理方式

请用 Unix 路径重新 build bundle，或在上传前清理压缩包路径。

canonical_path_fail

含义

Zip 内的文件路径不是规范路径。

处理方式

上传前修复归档路径的生成逻辑。

directory_path_fail

含义

Zip 包含无效的目录路径。

处理方式

上传前修复归档结构。

unzip_fail

含义

设备解压下载的 bundle 失败。

处理方式

请检查压缩包完整性及支持的压缩格式。

low_mem_fail

含义

下载失败，因为设备内存不足。

处理方式

请减小 bundle 体积，或在剩余内存更多的设备上重试。

App 健康状态与 WebView 事件

设备端崩溃、内存及 WebView 诊断。请务必在 dashboard 中检查 metadata JSON。

app_moved_to_background

含义

应用已进入后台。

app_moved_to_foreground

含义

应用已进入前台。

app_crash

含义

JavaScript 或 Capacitor 层崩溃。元数据可包含 message、stack、source 及当前 bundle 上下文。

处理方式

检查元数据和 native logs。结合 JS 与 native 错误报告（例如 Sentry）来定位出错的 code 路径。

app_crash_native

含义

Native 平台崩溃。元数据包含平台、原因、堆栈及进程详情。

处理方式

使用 Xcode 或 Logcat 的崩溃日志，并结合元数据中的当前 bundle 进行排查。

app_anr

含义

Android 应用无响应 (ANR) 事件。

处理方式

检查 Logcat 中的 ANR trace，并减少更新后主线程的阻塞任务。

app_killed_low_memory

含义

由于内存压力，操作系统已终止该应用。

处理方式

在激活更新后降低内存占用，并检查元数据中的可用内存信号。

app_killed_excessive_resource_usage

含义

操作系统因资源占用过高而终止了应用。

处理方式

检查元数据以获取资源类型或平台层面的原因。

app_initialization_failure

含义

在正常运行时就绪前，Updater 或启动过程失败。

处理方式

检查元数据以获取失败步骤和错误信息。

app_memory_warning

含义

iOS 内存警告。

处理方式

检查元数据中的内存上下文，并在更新后降低峰值占用。

webview_javascript_error

含义

WebView 中发生未捕获的 JavaScript 错误。元数据可包含错误消息、来源 URL、行号、列号及堆栈信息。

处理方式

在 JS 和原生层接入错误上报，以便在生产环境捕获具体出错行。

webview_unhandled_rejection

含义

WebView 中发生未处理的 Promise 拒绝。

处理方式

通过 JS 和原生错误报告捕获异步失败。

webview_resource_error

含义

WebView 资源加载失败。

处理方式

利用元数据 URL 和状态详情修复损坏的资源或网络规则。

webview_security_policy_violation

含义

内容安全策略 (CSP) 拦截了资源。

处理方式

根据元数据指令和被拦截的 URI 详情调整 CSP。

webview_unclean_restart

含义

上一次 WebView 会话未正常关闭，这可能表明更新后出现了崩溃循环。

处理方式

请结合重启前后的 crash 事件和 WebView error 事件进行排查。

webview_render_process_gone

含义

Android WebView 渲染进程已退出。

处理方式

请检查 metadata 和 native logs 中的渲染进程崩溃信号。

webview_content_process_terminated

含义

iOS WebView 内容进程已终止。

处理方式

通过元数据检查当前生效的 bundle 和页面 URL。

环境与 Channel 上下文

设备端上下文事件，用于将更新行为与 OS、原生版本或 Channel 变更进行关联。

os_version_changed

含义

在检查期间设备 OS 版本发生了变化。

native_app_version_changed

含义

原生 App Store 版本已变更，有助于区分原生代码与 web bundle 的变化。

getChannel

含义

设备已查询其当前 channel。

setChannel

含义

设备已成功设置 channel。

uninstall

含义

应用已卸载或 Capgo 数据已清除。

Bundle 状态

• SUCCESS: bundle 安装完成
• ERROR: 安装或下载失败
• PENDING: 下载完成，等待发布
• DELETED: Bundle 已删除，但仍显示在统计数据中
• DOWNLOADING: 正在下载 Bundle

理解设备日志

Debug 命令

Capgo 云端用户可以使用 debug 命令。

npx @capgo/cli@latest app debug

这将允许你检查 App 中发生的所有事件，并在更新未生效时找到解决方案。

iOS 原生日志

在 Xcode 中查找日志

在 Xcode 中获取设备日志

Android 原生日志

在 Android Studio 中查找日志

使用 Logcat 查看日志

原生日志短语映射

• Failed to download from 映射至 download_fail
• notifyAppReady was not called, roll back current bundle 映射至 update_fail

在设备上查找已下载的 bundle

iOS

要在 iOS 上进行调试，你需要将 App 导出到电脑上，操作步骤如下：

Xcode 内置了查看 iOS 设备上开发者安装的 App 文件系统的功能。

具体操作步骤：

• 将设备连接到 Mac，然后在 Xcode 菜单栏中选择 Window > Devices。
• 在左侧面板的 Devices 栏目下选择你的设备。
• 这会显示该设备上开发者安装的 App 列表。
• 选择你想要查看的 App，然后点击屏幕底部附近的三个点图标。
• 在这里，你可以选择下载文件系统快照来查看当前文件系统。

选择 Download Container… 会将文件系统快照下载并导出为 .xcappdata 文件，你可以浏览其中的内容。

右键点击此文件，选择 Show Package Contents 即可打开文件夹。

打开 App Data 文件夹后，你应该能看到 Documents、Library、tmp 等文件夹。

然后你会在两个文件夹中找到版本：

library/NoCloud/ionic_built_snapshots 在 App 重启后是必需的

以及 documents/versions 用于热重载

Android

若要在 Android 上进行调试，您需要通过 Android Studio 访问设备：

• 点击 View > Tool Windows > Device File Explorer，或点击工具窗口栏中的 Device File Explorer 按钮来打开它。
• 从下拉列表中选择一台设备。
• 打开路径 data/data/APP_NAME/ 其中 APP_NAME 是您的 App ID。

然后找到 versions 文件夹以查看所有版本

你知道吗？

在 Android 上，所有版本都存放在同一个文件夹中；而 iOS 则需要在两个位置各存一份。

解读 iOS 生产环境崩溃日志

如何查看应用的崩溃日志

继续阅读：调试

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