调试

复制一个包含安装步骤和本插件完整 Markdown 指南的配置提示。

理解云日志

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

Capgo 日志可能包含事件的元数据。在仪表板中，按蛇形小写动作 code 过滤，然后单击元数据单元格以复制完整的 JSONayload。元数据对于崩溃和 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（x.y.z).

做什么

设置 plugins.CapacitorUpdater.version 以有效的semver形式验证它，在 SemVer测试器,然后重建并重新安装原生应用。

平台和构建目标

后端拒绝

`disablePlatformIos`

什么意思

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

怎么办

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

`disablePlatformAndroid`

Section titled “disablePlatformAndroid”

Section titled “disablePlatformAndroid”

调试更新器

Section titled “disablePlatformElectron”

`disablePlatformElectron`

Section titled “disablePlatformAndroid”

Section titled “disablePlatformElectron”

调试更新器

Section titled “disableDevBuild”

`disableDevBuild`

Section titled “disablePlatformAndroid”

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

要做什么

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

`disableProdBuild`

它的含义

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

要做什么

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

`disableDevice`

它的含义

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

什么要做

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

`disableEmulator`

什么意思

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

什么要做

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

自动更新兼容性规则

禁用自动更新

`disableAutoUpdate`

什么意思

自动更新已被渠道兼容性策略禁用。元数据包括 auto_update 与一个匹配规则例如 major, minor, patch, metadata, 或 none.

要做什么

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

`disableAutoUpdateUnderNative`

什么意思

渠道有一个包比设备基线更旧，阻止发送更新在本机版本下。

要做什么

在本机基线以上发布一个包，或者在渠道中禁用本机保护。

`disableAutoUpdateMetadata`

什么意思

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

做什么

设置 min_update_version 从目标包或发布中从新版本机版本获取。

`disableAutoUpdateToMajor`

标题：“disableAutoUpdateToMajor”

它意味着什么 1.x.x to 2.x.x.

做什么

到与您的重大发布计划对齐频道策略，或者允许重大跳转此轨道。请参见“常见更新问题”.

`disableAutoUpdateToMinor`

什么意思

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

到

什么做

`disableAutoUpdateToPatch`

什么意思

Section titled “disableAutoUpdateToPatch” MAJOR.MINOR.PATCH 频道阻止了同名前缀的补丁级别更改；仅允许后缀更改

到

与渠道策略同步发布频率，或者允许此轨道的补丁跳跃。

渠道设置

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

`cannotUpdateViaPrivateChannel`

什么意思

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

在渠道上启用

Enable allow_device_self_set 渠道配置错误

`channelMisconfigured`

什么是它的含义

该频道使用 disable_auto_update: "version_number" 但是捆绑包 min_update_version 为 null，因此 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 代替本地 bundle 文件。 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%

`download_20`

说明

正在下载新包，进度20%

`download_30`

说明

正在下载新包，进度30%

`download_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`

什么意思

什么意思

怎么办

压缩设置有问题，重新上传受影响的资产。

`download_fail`

什么是它的含义

下载包失败。

要做什么

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

`update_fail`

什么是它的含义

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

要做什么

在应用程序启动后 notifyAppReady() 对应于这个 __CAPGO_KEEP_0__ notifyAppReady was not called, roll back current bundle 映射到这个 code。

`checksum_fail`

它意味着什么

下载的包校验失败。常见原因：CRC32与SHA256不符的旧CLI上传，或者加密密钥不符的旧插件会将解密失败呈现为校验失败。

如何处理

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

`decrypt_fail`

它意味着什么

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

如何处理

Section titled “Windows路径失败”

`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 未处理的承诺拒绝。

如何处理

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

Xcode 有一个内置功能，可以检查开发者安装的 iOS 设备上的文件系统。

Xcode 窗口菜单显示 Devices and Simulators 选项要实现这一点：

调试iOS

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

Xcode 设备面板显示应用程序容器下载选项

选择 Download Container… 将下载并导出文件系统快照的 .xcappdata 文件，您可以浏览其中的内容。

下载的 xcappdata 文件右键单击并选择 Show Package Contents 打开文件夹。

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

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

然后您将在 2 个文件夹中找到版本：

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

library/NoCloud/ionic_built_snapshots 需要在应用重启后进行

和 documents/versions 用于热重载

安卓

为了在安卓上调试，您需要从安卓 studio 访问设备：

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

Android Studio 设备文件浏览器显示应用数据目录

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

理解 iOS 生产崩溃日志

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

继续阅读 Debugging

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