Debugging

了解云日志

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

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

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

计划限制和正常响应

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

InvalidIp

它是什么意思

Capgo 检测到来自 Google 或云基础设施的流量。更新时间小于四小时的请求会被忽略，以免bot流量被计入可计费设备中。

什么要做

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

provider_infrastructure_request_blocked

什么意思

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

什么要做

从物理设备上正常用户网络重试。如果提供商源出的流量是有意的，请暂时禁用 在应用程序的 信息 选项卡中禁用 provider_infrastructure 请求，然后在测试后再启用。新应用程序默认启用此设置；已有应用程序保留其之前的禁用设置，直到更改为止。 Section titled “provider_infrastructure_request_blocked” is not translated as it is a title and not a text to be translated.

needPlanUpgrade

是什么意思

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

怎么办

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

noNew

是什么意思

设备已经有最新的bundle

rateLimited

设备发送了太多的更新或频道请求

怎么办

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

不要在渲染循环中调用更新API。 setChannel / getChannel 只在用户操作中调用，设置 defaultChannel 在 capacitor.config.

版本格式

由于本地版本元数据无效而导致的后端拒绝。

semver_error

什么意思

配置中的本地应用程序版本丢失或不符合semver（x.y.z).

怎么办

将其设置为有效的semver，验证它在 plugins.CapacitorUpdater.version __CAPGO_KEEP_0__ 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”的部分.

disableAutoUpdateToMinor

__CAPGO_KEEP_0__

与设备本地基线相对的次版本跳转（version_build例如 1.2.3 要做什么 1.3.0.

将渠道策略与次版本发布计划对齐，或者允许此跟踪器的次版本跳转

标题："disableAutoUpdateToPatch"

disableAutoUpdateToPatch

渠道阻止了同一

前缀；仅允许后缀变化 MAJOR.MINOR.PATCH 要做什么

将发布频率与渠道策略对齐，或者允许此跟踪器的补丁跳转

渠道设置

__CAPGO_KEEP_0__

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

cannotUpdateViaPrivateChannel

什么意思

设备尝试与一个不允许设备自我分配的私有频道进行自我关联（is false）且该频道不是公共频道allow_device_self_set 怎么办

在频道中启用

或切换设备到公共频道或允许的频道 allow_device_self_set 频道配置错误

channelMisconfigured

频道使用

__CAPGO_KEEP_0__ disable_auto_update: "version_number" 但捆绑包是空的，所以__CAPGO_KEEP_0__无法决定哪些设备应该更新。 min_update_version is null, so Capgo cannot decide which devices should update.

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

什么可以做

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

什么意思

The app sent a custom device ID, but this app does not accept custom IDs, so the ID is ignored.

What to do

Stop sending custom IDs, or enable custom IDs only when your workflow requires them.

blocked_by_server_url

What it means

server.url 是通过 Capacitor 配置设置的，因此 WebView 加载远程 URL 而不是本地 bundle 文件。 Capgo 实时更新需要本地文件， server.url 是生产环境中不建议使用的。

What to do

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

backend_refusal

What it means

The updater plugin is v4, which the backend no longer accepts.

What to do

Upgrade plugin and CLI to v5+ (prefer v8) with Capacitor v5+, rebuild, and republish bundle metadata.

Update lifecycle

Device-side events for normal update flow, activation, and rollback.

ping

What it means

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

get

What it means

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

这是什么意思

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

download_50

这是什么意思

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

download_60

这意味着什么

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

download_70

这意味着什么

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

download_80

这意味着什么

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

download_90

这意味着什么

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

download_complete

什么意思

下载成功

download_manifest_start

什么意思

设备开始下载更新清单

download_manifest_complete

什么意思

设备下载更新清单完成

download_zip_start

什么意思

The device started downloading the bundle archive.

download_zip_complete

What it means

设备下载完成

download_manifest_file_fail

下载失败

What it means version_name 下载失败 version:fileName uses

用来识别资产。

What to do

download_manifest_checksum_fail

什么是它

__CAPGO_KEEP_0__包文件校验失败。

解决方法

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

download_manifest_brotli_fail

什么是它

__CAPGO_KEEP_0__包文件Brotli解压失败。

解决方法

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

download_fail

什么是它

包文件下载失败。

What to do

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

update_fail

What it means

The bundle installed but the app never called notifyAppReady, so Capgo rolled back.

所以__CAPGO_KEEP_0__回滚了。

Call notifyAppReady() after your app finishes bootstrapping. Native log text notifyAppReady was not called, roll back current bundle maps to this code.

checksum_fail

What it means

下载的包校验失败。常见原因：CRC32与SHA256不符的旧CLI上传，或者旧版插件中加密密钥不符导致的校验失败。

解决方案

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

decrypt_fail

解释

下载的包解密失败。

解决方案

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

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 or Capacitor layer crash. Metadata can include message, stack, source, and active bundle context.

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

Inspect metadata and native logs. Pair JS and native error reporting (for example Sentry) to locate the failing code path.

app_crash_native

什么意思

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

如何处理

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

app_anr

什么意思

Android应用程序未响应事件。

如何处理

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

app_killed_low_memory

什么意思

The OS killed the app due to memory pressure.

What to do

After updating, reduce memory usage and check for available memory signals.

app_killed_excessive_resource_usage

What it means

The OS killed the app for excessive resource use.

What to do

Check the metadata for the resource type or platform reason.

app_initialization_failure

What it means

The updater or startup failed before the app was ready.

What to do

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

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 版本更改

os_version_changed

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

原生应用程序版本更改

native_app_version_changed

什么是它

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

getChannel

什么是它

设备查询了当前的频道。

setChannel

什么是它

设备设置频道成功。

uninstall

什么是它

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

打包状态

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

理解设备日志

调试命令

Capgo 为 Capgo 云用户提供了一个调试命令。

npx @capgo/cli@latest app debug

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

iOS 原生日志

在 Xcode 中找到您的日志

在 Xcode 中获取设备日志

Android 原生日志

在 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 文件夹

在应用程序重启后是必要的

library/NoCloud/ionic_built_snapshots 并且

并且 documents/versions 热重载

Android

要在 Android 上调试，您需要从 Android Studio 访问设备：

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

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

你知道吗？

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

理解 ios 生产崩溃日志

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

继续 Debugging

Debugging 以规划原生插件工作，连接它 以规划原生插件工作，连接它 使用 @capgo/capacitor-updater 使用 @capgo/capacitor-updater Capgo 插件目录 Capgo 插件目录 Capacitor 由 Capgo 提供的插件 Capacitor 由 Capgo 提供的插件 添加或更新插件 添加或更新插件 Ionic 企业插件替代方案 Ionic 企业插件替代方案