Debugging

理解云日志

如果您收到云拒绝 code 并需要更深入的修复教程，请参阅 常见更新问题.

Capgo 日志可能包含事件的元数据。在仪表板中，过滤以 code 为蛇形名称的事件，然后点击元数据单元格以复制完整的 JSONayload。元数据对于崩溃和 WebView 事件特别有用，因为它可以包含错误消息、源 URL、行号和列号、进程状态、内存压力或平台特定原因。旧日志仍然可以显示遗留的 camelCase 别名（括号内列出）。

每个部分标题都与控制台日志表中显示的 code 动作匹配，因此您可以直接链接到它。

计划限制和正常响应

与账单、限速或非错误状态相关的后端拒绝。

InvalidIp

什么意思

Capgo检测到来自Google或云基础设施的流量。更新时间小于四小时的流量不会计入可计费设备。

怎么办

忽略真实用户的流量。从正常网络和真实设备重试，或者稍后再检查。

provider_infrastructure_request_blocked

什么意思

您的应用程序配置为阻止来自Google和Apple数据中心IP范围的请求。保护措施适用于更新检查、统计和channel-self请求，因此云托管探针和提供商运行器即使应用程序配置有效时也可能收到此响应。

怎么办

从物理设备上正常用户网络重试。如果提供商源出的流量是有意的，请暂时禁用 阻止提供商基础设施请求 在应用程序的 信息 tab中，测试后再启用它。新应用程序通过默认启用此设置；现有应用程序保留其之前的禁用设置，直到更改。

needPlanUpgrade

它意味着什么

您的组织已达到计划或设备限制。设备将不会接收更新，直到您升级或下一个billing周期重置使用。

您应该做什么

在控制台中升级您的计划或等待下一个billing周期。

noNew

它意味着什么

设备已经有最新的包可用，属于其频道。这是正常状态，不是故障。

rateLimited

什么意思

设备在短时间内发送了太多的更新或频道请求。

怎么办

不要在渲染循环中调用更新API。从用户操作中调用 setChannel / getChannel 并设置 defaultChannel 版本格式 capacitor.config.

标题：版本格式

标题：semver_error

semver_error

本地应用程序版本在配置中丢失或无效的semver（

semver_errorx.y.z).

如何操作

设置 plugins.CapacitorUpdater.version 将其设置为有效的semver，通过SemVer测试器验证，然后重建并重新安装原生应用。 SemVer测试器平台和构建目标

平台和构建目标

禁用iOS平台

disablePlatformIos

设备运行iOS，但在此通道中禁用了iOS更新。

如何操作

platform and build targeting

如果这是意外的，请在通道中启用 iOS，或者当阻塞是有意的时，将 iOS 构建路由到专门的通道。

disablePlatformAndroid

什么意思

设备运行 Android，但在此通道中禁用了 Android 更新。

如何处理

如果这是意外的，请在通道中启用 Android，或者当阻塞是有意的时，将 Android 构建路由到专门的通道。

disablePlatformElectron

什么意思

设备运行 Electron，但在此通道中禁用了 Electron 更新。

如何处理

如果这是意外的，请在通道中启用 Electron，或者当阻塞是有意的时，将 Electron 构建路由到专门的通道。

disableDevBuild

什么意思

设备是开发版，但本渠道已阻止开发版

怎么办

允许在测试渠道中启用开发版，或者将开发版设备移到其他渠道

disableProdBuild

什么意思

一个生产版 /updates，但生产版更新已在本渠道被阻止

怎么办

如果这是意外，请允许在本渠道中启用生产版更新，或者将生产版构建路由到正确的渠道

disableDevice

什么意思

因为这个频道阻止了真实设备，这个真实的手机或平板被阻止了。

解决方案

如果这是意外的，请启用真实设备更新，或者保持限制并将真实设备路由到另一个频道。

disableEmulator

解释

设备是模拟器，但模拟器更新在这个频道中被禁用。

解决方案

在测试频道中启用模拟器更新，或者保持这个频道禁用模拟器并使用另一个频道进行模拟器验证。

自动更新兼容性规则

后端拒绝，当semver或元数据规则阻止目标包时。

disableAutoUpdate

什么意思

由于渠道兼容性策略，自动更新已被禁用。元数据包括 auto_update 例如 major, minor, patch, metadata或 none.

什么要做

更改渠道自动更新策略以允许您的意图部署。

disableAutoUpdateUnderNative

什么意思

渠道有一个比设备基线更旧的捆绑包，并阻止在原生版本下发送更新。

什么要做

发布一个在原生基线以上的捆绑包，或者在渠道中禁用原生保护。

disableAutoUpdateMetadata

什么是它的含义

该频道需要 min_update_version, 但设备原生版本低于该阈值。

什么要做

设置 min_update_version 在目标包或发布中使用较新原生版本。

disableAutoUpdateToMajor

什么是它的含义

该频道阻止主版本跳转，例如 1.x.x 到 2.x.x.

什么要做

使频道策略与您的主版本发布计划保持一致，或者允许此轨道的主版本跳转。请参见 常见更新问题.

disableAutoUpdateToMinor

什么意思

该频道阻止设备本地基线相对于的次要版本跳转（例如version_build) 1.2.3 例如 1.3.0.

什么做

将频道策略与次要发布计划对齐，或允许此跟踪的次要跳转

disableAutoUpdateToPatch

什么意思

该频道阻止补丁级别的变化，同时保持相同的 MAJOR.MINOR.PATCH 前缀；仅允许后缀变化

如何操作

与渠道策略对齐的发布节奏，或允许此轨道的补丁跳跃。

渠道设置

由于缺失或不兼容的渠道配置，导致后端拒绝。

cannotUpdateViaPrivateChannel

什么意思

设备尝试与不允许设备自我分配的私有渠道自我关联（is false）且渠道不是公共的。allow_device_self_set 如何操作

在渠道上启用

或切换设备到公共或允许的渠道 allow_device_self_set switch the device to a public or allowed channel.

channelMisconfigured

什么意思

该频道使用 disable_auto_update: "version_number" 但是包 min_update_version 是空的，所以Capgo无法决定哪些设备应该更新。

解决方法

填写缺失的配置规则或切换到更简单的自动更新模式。

NoChannelOrOverride

什么意思

没有配置默认频道，设备也没有频道覆盖。

解决方法

在控制台中设置一个默认频道或配置 defaultChannel 在构建中。

包裹传递和加密

后端拒绝服务或无法解密包裹时，Capgo

cannotGetBundle

什么意思

Capgo 生成有效的签名下载 URL 失败，没有可用清单回退

怎么办

重新上传包裹，重新生成清单，验证 R2 或公共包裹设置

missingBundle

什么意思

分配给频道的包裹没有可下载的内容：没有 external_url, 不支持 r2_path, 不是内置版本，且没有清单项。

什么要做

重建并重新上传版本，然后确认包中有真实文件内容。

keyMismatch

什么意思

设备加密公钥与用来加密包的密钥不匹配。元数据可以包括 device_key_id, bundle_key_id, 和 version.

什么要做

在控制台中比较设备和包密钥ID。使用相同的密钥和匹配的CLI/插件版本发布。

应用配置和遗留客户端

后端拒绝可能是由应用配置或不支持的更新器版本引起的。

customIdBlocked

什么意思

应用程序发送了一个自定义设备 ID，但该应用程序不接受自定义 ID，因此 ID 被忽略。

如何解决

停止发送自定义 ID，或者在您的工作流程需要它们时启用自定义 ID。

blocked_by_server_url

什么意思

server.url 在 Capacitor 配置中设置，因此 WebView 加载远程 URL 代替本地捆绑文件。 Capgo 实时更新需要本地文件并 server.url 在生产环境中不建议使用。

如何解决

清除或移除 server.url 用于生产构建并保持更新负载本地。这 code 可以作为后端拒绝或作为设备侧状态出现。

backend_refusal

它意味着什么

更新器插件是 v4，后端不再接受。

要做什么

升级插件和 CLI 到 v5+（优先 v8），并且 Capacitor v5+，重建并重新发布包元数据。

更新生命周期

设备侧事件用于正常更新流程、激活和回滚。

ping

它意味着什么

内部测试动作，用于验证统计管道。

get

What it means

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

set

What it means

设备上激活了一个包。

set_fail

What it means

What to do

检查本地日志并

验证包的完整性、路径和 npx @capgo/cli@latest app debug and verify bundle integrity, paths, and notifyAppReady 流程。

reset

什么意思

设备重置为内置包。

delete

什么意思

下载和安装失败

标题：“下载和安装失败”

标题：“下载_0”

download_0

标题：“下载进度”

下载序列已开始，进度为0%。

download_10

什么意思

已下载新包，进度为10%。

download_20

什么意思

已下载新包，进度为20%。

download_30

什么意思

已下载新包，进度为30%。

download_40

什么意思

已下载一个新包 — 进度已指示为40%。

download_50

这意味着什么

已下载一个新包 — 进度已指示为50%。

download_60

这意味着什么

已下载一个新包 — 进度已指示为60%。

download_70

这意味着什么

已下载一个新包 — 进度已指示为70%。

download_80

这意味着什么

A new bundle has been downloaded — progress indicated at 80%.

download_90

What it means

下载完成

download_complete

下载完成

What it means

download_manifest_start

下载更新清单开始

What it means

download_manifest_complete

下载更新清单完成

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

download_zip_start

这意味着什么

设备已开始下载捆绑包存档。

download_zip_complete

这意味着什么

设备已完成下载捆绑包存档。

download_manifest_file_fail

这意味着什么

下载一个清单条目失败。 version_name 用于 version:fileName 识别资产

解决方法

修复缺失或被阻止的资源，重新生成清单，重新上传包。

download_manifest_checksum_fail

是什么意思

清单文件校验和验证失败。

解决方法

Re-upload the bundle with a current CLI version and verify manifest checksums.

download_manifest_brotli_fail

是什么意思

清单文件Brotli解压失败。

解决方法

验证压缩设置并重新上传受影响的资源。

download_fail

是什么意思

下载包失败。

如何解决

检查网络连接、签名 URL 过期、CDN 可达性和设备存储。

update_fail

是什么意思

安装包成功，但应用程序从未调用 notifyAppReady所以 Capgo 回滚了。

如何解决

在应用程序启动完成后调用 notifyAppReady() native 日志文本 notifyAppReady was not called, roll back current bundle maps to this code.

checksum_fail

什么意思

下载的包校验和验证失败。常见原因：CRC32与SHA256不符，可能是旧版本的CLI上传，或者加密密钥不符，导致旧版本插件表面解密失败作为校验失败。

怎么办

重新上传一个当前版本的CLI/插件（SHA256）。如果使用加密，请验证应用公钥与上传密钥匹配，或者升级到插件8.3.0+，以显示明确的 keyMismatch 错误。

decrypt_fail

什么意思

下载的包解密失败。

怎么办

验证加密密钥并重新上传包使用匹配的密钥pair。

windows_path_fail

什么意思

压缩包包含非法的Windows路径。

如何解决

在Unix路径下重新构建包或在上传前清理压缩包路径。

canonical_path_fail

什么意思

压缩包内的文件路径不是规范的。

如何解决

在上传前修复压缩包路径生成。

directory_path_fail

什么意思

压缩包包含无效的目录路径。

如何处理

在上传前修复压缩包结构。

unzip_fail

解释

设备无法解压下载的包文件。

如何处理

验证压缩包完整性和支持的压缩格式。

low_mem_fail

解释

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

如何处理

减小包大小或在有更多空闲内存的设备上重试。

App健康和WebView事件

设备端崩溃、内存和WebView诊断。总是检查仪表盘中的元数据JSON。

app_moved_to_background

什么意思

应用程序进入后台。

app_moved_to_foreground

什么意思

应用程序进入前台。

app_crash

什么意思

JavaScript 或 Capacitor层崩溃。元数据可以包含消息、堆栈、源代码和活动包上下文。

什么要做

检查元数据和本机日志。将JS和本机错误报告（例如Sentry）配对，以定位失败的code路径。

app_crash_native

什么意思

本机平台崩溃。元数据可以包含平台、原因、堆栈和进程详细信息。

什么要做

使用Xcode或Logcat崩溃日志，并与元数据中的活动包进行关联。

app_anr

什么意思

Android应用程序未响应事件。

什么要做

在 Logcat 中检查 ANR 跟踪并在更新后减少主线程阻塞工作。

app_killed_low_memory

它意味着什么

操作系统在内存压力下杀死了应用。

如何处理

在更新激活后减少内存使用，并检查可用内存信号的元数据。

app_killed_excessive_resource_usage

它意味着什么

操作系统杀死了应用程序，因为资源使用过多。

如何处理

检查资源类型或平台原因的元数据。

app_initialization_failure

什么是它的含义

更新器或启动器在正常运行时间准备好之前失败了。

什么要做

检查元数据以确定失败的步骤和错误消息。

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

什么意思

内容安全策略阻止了一个资源。

怎么办

使用元数据指令和阻止URI的详细信息调整CSP。

webview_unclean_restart

什么意思

之前的WebView会话没有正常关闭，这可能指示在更新后出现的死循环。

怎么办

在重启之前和之后与崩溃和WebView错误事件相关联。

webview_render_process_gone

什么意思

Android WebView 渲染进程已退出。

如何处理

检查元数据和本机日志中的渲染器崩溃信号。

webview_content_process_terminated

什么意思

iOS WebView 内容进程已终止。

如何处理

检查元数据中的活动包和页面 URL。

环境和渠道上下文

设备侧上下文事件，帮助协调更新行为与 OS、native 版本或渠道变化。

os_version_changed

什么意思

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

native_app_version_changed

什么意思

原生应用商店版本发生了变化，帮助区分原生和web包的变化。

getChannel

什么意思

设备查询了其当前频道。

setChannel

什么意思

设备设置频道成功。

uninstall

它意味着什么

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

包状态

• SUCCESS:安装包完成
• ERROR:安装或下载失败
• PENDING:下载完成，等待发布
• DELETED:包已删除，但仍用于统计
• DOWNLOADING:当前正在下载包

理解设备日志

调试命令

对于Capgo云用户，有一个调试命令。

npx @capgo/cli@latest app debug

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

iOS原生日志

在Xcode中获取设备日志

Android原生日志

在Android Studio中找到您的日志

在Android Studio中找到您的日志

查看 Logcat 日志

原生日志短语映射

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

在设备上找到下载的包

iOS

在 iOS 上调试时，您需要将应用程序下载到您的计算机上，方法如下：

Xcode 内置了一个用于检查 iOS 设备上开发者安装的应用程序文件系统的功能。

为了实现这一点:

• 连接您的设备到您的Mac并在Xcode菜单栏中选择窗口>设备。
• 在左侧的设备部分中选择您的设备。
• 这将显示该设备上开发者安装的应用程序列表。
• 选择您要检查的应用程序，然后选择屏幕底部附近的3个点图标。
• 您可以通过选择下载该文件系统的快照来查看当前文件系统。

选择下载容器…将下载并导出文件系统快照的.xcappdata文件，您可以浏览该文件。

打开App Data文件夹，您现在应该看到几个文件夹，如文档、库、tmp等。

iOS应用程序容器文件夹结构显示文档和库文件夹

然后你会在2个文件夹中找到一个版本:

library/NoCloud/ionic_built_snapshots 在应用重启后是必要的

并 documents/versions 用于热重载

安卓

为了在安卓上调试，你需要从安卓Studio访问设备:

• 点击视图>工具窗口>设备文件浏览器或在工具窗口栏中点击设备文件浏览器按钮来打开设备文件浏览器。
• 从下拉列表中选择一个设备。
• 打开路径 数据/data/APP_NAME/ 在 APP_NAME 是您的应用程序 ID。

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

您知道吗？

在 Android 上，所有版本都存储在一个文件夹中，而不是 iOS，需要在两个位置复制。

了解 iOS 生产崩溃日志

如何查看您的应用程序崩溃日志

继续从 Debugging

如果您正在使用 调试 来规划原生插件工作，连接它与 使用@capgo/capacitor-updater 为原生能力在使用@capgo/capacitor-updater Capgo插件目录 为产品工作流程在Capgo插件目录 Capacitor插件由Capgo 为实现细节在Capacitor插件由Capgo 添加或更新插件 为实现细节在添加或更新插件 Ionic企业插件替代方案 为 Ionic Enterprise Plugin Alternatives 产品工作流程。