Debugging

理解云日志

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

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

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

计划限制和正常响应

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

InvalidIp

什么意思

Capgo检测到来自Google或云基础设施的流量。更新时间小于四小时的流量将被忽略，以免机器人流量被计入可计费设备。

如何处理

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

provider_infrastructure_request_blocked

什么意思

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

如何处理

从物理设备上正常用户网络重试。如果提供商生成的流量是有意的，请暂时禁用 阻止提供商基础设施请求 在应用程序中 信息 在应用程序的

needPlanUpgrade

它意味着什么

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

您应该做什么

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

noNew

它意味着什么

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

rateLimited

什么是它的含义

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

如何处理

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

标题为“版本格式”的部分

标题为“semver_error”的部分

semver_error

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

__CAPGO_KEEP_0__x.y.z).

如何操作

设置 plugins.CapacitorUpdater.version 确保为有效的semver，通过 SemVer 测试器然后重建并重新安装原生应用

平台和构建目标

后端拒绝

disablePlatformIos

禁用 iOS 平台

禁用 iOS 平台

什么意思

如果这是意外的，请在通道中启用 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 渠道设置

channelMisconfigured

什么意思

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

解决方法

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

NoChannelOrOverride

什么意思

没有配置默认频道且设备没有频道覆盖

解决方法

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

包裹传递和加密

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

cannotGetBundle

什么意思

Capgo 生成有效的签名下载 URL 失败，没有 manifest 降级

怎么办

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

missingBundle

什么意思

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

什么要做

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

keyMismatch

什么意思

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

什么要做

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

应用配置和遗留客户端

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

customIdBlocked

什么意思

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

如何解决

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

blocked_by_server_url

什么意思

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

如何解决

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

backend_refusal

它的含义

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

解决方法

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

更新生命周期

ping

ping

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

__CAPGO_KEEP_1__

get

What it means

Capgo 将下载信息发送到设备，提示有新版本可下载。

set

What it means

设备上激活了一个包。

set_fail

What it means

设备上激活包失败。

What to do

检查本地日志中 npx @capgo/cli@latest app debug 并验证包的完整性、路径等 notifyAppReady 流程。

reset

什么意思

设备重置为内置包。

delete

什么意思

下载和安装失败

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

标题：“下载_0”

download_0

标题：“下载进度”

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

download_10

什么意思

已下载新包装 — 进度指示为 10%。

download_20

什么意思

已下载新包装 — 进度指示为 20%。

download_30

什么意思

已下载新包装 — 进度指示为 30%。

download_40

什么意思

A新包已下载 — 进度已达40%。

download_50

说明

A新包已下载 — 进度已达50%。

download_60

说明

A新包已下载 — 进度已达60%。

download_70

说明

A新包已下载 — 进度已达70%。

download_80

说明

已下载一个新包 — 进度已达到80%。

download_90

这意味着什么

已下载一个新包 — 进度已达到90%。

download_complete

这意味着什么

包下载成功完成。

download_manifest_start

这意味着什么

设备开始下载更新清单。

download_manifest_complete

这意味着什么

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

download_zip_start

这是什么意思

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

download_zip_complete

这是什么意思

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

download_manifest_file_fail

这是什么意思

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

解决方法

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

download_manifest_checksum_fail

是什么意思

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

解决方法

重新上传当前CLI版本的包并验证清单校验和。

download_manifest_brotli_fail

是什么意思

清单文件Brotli解压失败。

解决方法

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

download_fail

是什么意思

下载包失败。

如何解决

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

update_fail

是什么意思

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

如何解决

在应用程序完成引导后调用 notifyAppReady() 原生日志文本 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

decrypt_fail

下载的包解密失败。

怎么办

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

__CAPGO_KEEP_0__

windows_path_fail

什么意思

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

如何解决

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

canonical_path_fail

什么意思

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

如何解决

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

directory_path_fail

什么意思

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

如何处理

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

unzip_fail

解释

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

如何处理

验证压缩包完整性和支持的压缩算法。

low_mem_fail

解释

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

如何处理

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

应用健康和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

什么意思

设备操作系统版本在检查之间发生了变化。

native_app_version_changed

什么意思

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

getChannel

什么意思

设备查询了其当前频道。

setChannel

什么意思

设备设置频道成功。

uninstall

什么是它的含义

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

捆绑状态

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

理解设备日志

调试命令

仅有 Capgo 云用户才有此 debug 命令。

npx @capgo/cli@latest app debug

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

iOS 本机日志

在 Xcode 中获取设备日志

Android 本机日志

在 Android Studio 中找到您的日志

Section titled “Android native logs”

查看日志使用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 文件夹，您应该现在看到几个文件夹，如 Documents、Library、tmp 等。

iOS 应用程序容器文件夹结构显示 Documents 和 Library 文件夹

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

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

并且 documents/versions 用于热重载

安卓

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

• 点击视图 > 工具窗口 > 设备文件浏览器或点击工具窗口栏上的设备文件浏览器按钮打开设备文件浏览器。
• 从下拉列表中选择一个设备。
• 打开路径 data/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 产品工作流程。