Debugging

理解云日志

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

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

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

计划限制和正常响应

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

InvalidIp

什么意思

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

如何处理

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

provider_infrastructure_request_blocked

什么意思

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

如何处理

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

needPlanUpgrade

标题：需要升级计划

它意味着什么

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

您应该做什么

noNew

标题：没有新版本

它意味着什么

rateLimited

什么是它的含义

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

什么要做

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

版本格式

后端拒绝由无效的本机版本元数据引起的

semver_error

什么是它的含义

本机应用程序版本在配置中丢失或无效的semver（x.y.z).

如何处理

设置 plugins.CapacitorUpdater.version 使其有效的 SemVer，验证它在 SemVer 测试器 中，然后重建并重新安装本机应用。 SemVer 测试器然后重建并重新安装本机应用。

平台和构建目标

后端拒绝

disablePlatformIos

禁用 iOS 平台

禁用 iOS 平台

什么意思？

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

disablePlatformAndroid

什么意思

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

怎么办

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

disablePlatformElectron

什么意思

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

怎么办

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

disableDevBuild

什么是它的含义

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

要做什么

允许在测试渠道中启用开发版本，或者将此渠道保持为只发布生产版本，并将开发设备转移到其他渠道

disableProdBuild

什么是它的含义

一个生产版本被称为 /updates,但生产更新已在本渠道中被阻止

要做什么

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

disableDevice

什么是它的含义

A real phone or tablet was blocked because this channel blocks real devices.

解决方法

如果这是意外的，请启用此频道允许的真实设备更新；如果不想允许真实设备更新，请将真实设备路由到另一个频道。

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 __CAPGO_KEEP_0__

如何操作

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

渠道设置

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

cannotUpdateViaPrivateChannel

什么意思

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

启用

在渠道上启用或切换设备到公共或允许的渠道。 allow_device_self_set Section titled “Channel setup”

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配置中设置了Capacitor，所以WebView加载远程URL而不是本地bundle文件。Capgo实时更新需要本地文件并 server.url 不建议在生产环境中使用。

如何解决

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

backend_refusal

它意味着什么

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

如何解决

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

更新生命周期

ping

ping

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

__CAPGO_KEEP_0__

get

它的含义

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

set

它的含义

设备上激活了一个包。

set_fail

它的含义

解决方案

检查本地日志并

验证包的完整性、路径等 npx @capgo/cli@latest app debug 和 notifyAppReady 流程。

reset

什么意思

设备重置到内置包。

delete

什么意思

设备上删除了一个包。

下载和安装失败

设备端事件：下载进度、存档验证和安装错误。

download_0

什么意思

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

download_10

什么意思

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

download_20

什么意思

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

download_30

什么意思

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

download_40

什么意思

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

download_50

这意味着什么

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

download_60

这意味着什么

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

download_70

这意味着什么

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

download_80

这意味着什么

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

download_90

What it means

下载完成

download_complete

下载完成

The bundle download finished successfully.

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

是什么意思

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

解决方法

使用最新的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

下载的包解密失败。

怎么办

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

Section titled “errors”

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应用程序未响应事件。

要做什么

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

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

然后你会在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 产品工作流程。