Debugging

理解云日志

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

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

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

计划限制和正常响应

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

InvalidIp

什么意思

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

如何处理

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

provider_infrastructure_request_blocked

什么意思

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

如何处理

从物理设备上正常用户网络重试。如果提供商源出的流量是有意的，请暂时禁用 Block provider infrastructure requests 在应用程序的 信息 请切换到调试模式，测试完成后再重新启用它。新应用程序默认启用此设置；已有应用程序保留其之前的禁用设置，直到更改。

needPlanUpgrade

什么意思

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

如何处理

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

noNew

什么意思

设备已经具有其频道的最新捆绑包。这是正常状态，不是故障。

rateLimited

什么意思

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

什么要做

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

版本格式

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

semver_error

什么意思

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

什么要做

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

平台和构建目标

后端拒绝

disablePlatformIos

标题为“disablePlatformIos”

什么意思

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

怎么办？

disablePlatformAndroid

什么意思

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

如何处理

如果这是意外，请在频道中启用 Android；如果这是有意的，请将 Android 构建路由到专门的频道。

disablePlatformElectron

什么意思

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

如何处理

如果这是意外，请在频道中启用 Electron；如果这是有意的，请将 Electron 构建路由到专门的频道。

disableDevBuild

什么意思

该设备是开发版，但本频道已阻止开发版。

要做什么

在测试频道中允许开发版，或者将开发设备移到其他频道，保持本频道的发布版状态。

disableProdBuild

什么意思

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

要做什么

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

disableDevice

什么意思

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

什么要做

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

disableEmulator

什么意思

设备是模拟器，但本频道禁用模拟器更新。

什么要做

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

自动更新兼容性规则

什么意思

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 什么做

disableAutoUpdateToPatch

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

渠道设置

由于缺失或不兼容的渠道配置，后端拒绝了更新请求。

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, 不是内置版本，也没有清单条目。

什么要做

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

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

什么意思

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

set

什么意思

设备上激活了一个包。

set_fail

什么意思

设备上激活包失败。

要做什么

检查原生日志并 npx @capgo/cli@latest app debug 验证包完整性、路径和 notifyAppReady 流程。

reset

什么意思

设备重置到内置包中。

delete

什么意思

设备上删除了一个包。

下载和安装失败

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

download_0

什么意思

下载序列开始于0%进度。

download_10

下载进度：10%

一个新包已下载，进度已达到10%。

download_20

下载进度：20%

一个新包已下载，进度已达到20%。

download_30

下载进度：30%

一个新包已下载，进度已达到30%。

download_40

下载进度：40%

一个新包已下载，进度已达到40%。

download_50

说明

下载新包时，进度已达到50%。

download_60

说明

下载新包时，进度已达到60%。

download_70

说明

下载新包时，进度已达到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() 对应于这个__CAPGO_KEEP_0__。 notifyAppReady was not called, roll back current bundle maps to this code.

checksum_fail

什么意思

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

怎么办

重新上传一个当前CLI/插件（SHA256）。如果使用加密，验证应用公钥是否与上传密钥匹配，或者升级到插件8.3.0+，以显示明确的 keyMismatch Section titled “decrypt_fail”

decrypt_fail

下载的包解密失败。

怎么办

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

Section titled “windows_path_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或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 未处理的承诺拒绝。

怎么办

使用 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_version_changed

os_version_changed

环境和渠道上下文

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

native_app_version_changed

什么意思

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

getChannel

什么意思

设备查询了其当前频道。

setChannel

什么意思

为设备设置了频道。

uninstall

什么意思

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

更新包状态

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

理解设备日志

调试命令

有一个调试命令专门为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 菜单栏中的 Window > Devices。
• 在 Devices 部分的左侧面板中选择您的设备。
• 这将显示该设备上开发者安装的应用程序列表。
• 选择您要检查的应用程序，然后选择屏幕底部附近的 3 个点图标。
• 您可以通过选择下载应用程序快照来查看当前文件系统。

选择 Download Container… 将下载并导出应用程序文件系统的快照，作为一个 .xcappdata 文件供您浏览。

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

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

__CAPGO_KEEP_0__

library/NoCloud/ionic_built_snapshots is necessary after the app reboot

and documents/versions for hot reload

Android

To debug on Android, you need to access the device from Android Studio:

• Click View > Tool Windows > Device File Explorer or click the Device File Explorer button in the tool window bar to open the Device File Explorer.
• Select a device from the dropdown list.
• Open the path data/data/APP_NAME/ where APP_NAME is your app ID.

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

你知道吗?

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

理解 iOS 生产崩溃日志

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

继续从 Debugging

如果您正在使用 调试 为了计划本机插件工作，连接它 使用@capgo/capacitor-updater 为了本机能力在使用@capgo/capacitor-updater中 Capgo插件目录 为了产品工作流程在Capgo插件目录中 Capacitor插件由Capgo 为了实现细节在Capacitor插件由Capgo中 添加或更新插件 为了实现细节在添加或更新插件中，并且 Ionic企业插件替代品 为了产品工作流程在Ionic企业插件替代品中