Updater {0} 仓库

理解云日志

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

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

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

Plan limits 和正常响应

与 billing、throttling 或非错误状态相关的后端拒绝。

InvalidIp

什么意思

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

怎么办

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

needPlanUpgrade

什么意思

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

怎么办

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

noNew

什么意思

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

rateLimited

什么意思

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

怎么办

在用户操作时调用 setChannel / getChannel update defaultChannel APIs， capacitor.config.

不要在渲染循环中调用。设置在用户操作时调用。版本格式

由于本地版本元数据无效，导致后端拒绝服务。

semver_error

什么意思

配置中的本地应用版本缺失或不符合semver（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

What it means

该渠道的包裹版本比设备的基线版本要旧，阻止发送更新到原生版本。

What to do

在渠道中发布一个版本或以上的原生基线版本，或者禁用渠道中的原生保护。

disableAutoUpdateMetadata

What it means

该渠道要求 min_update_version,但设备的原生版本低于该阈值。

What to do

在目标包裹或发布中设置 min_update_version disableAutoUpdateToMajor

disableAutoUpdateToMajor

它的含义

该频道阻止主要版本跳转，例如 1.x.x 到 2.x.x.

要做什么

将频道策略与主要发布计划对齐，或者允许此跟踪的主要跳转。请参见 常见更新问题.

disableAutoUpdateToMinor

它的含义

该频道阻止与设备本机基线（version_build)相对的次要版本跳转，例如 1.2.3 到 1.3.0.

要做什么

与次要发布计划对齐您的频道策略，或者允许此轨道的次要跳跃。

disableAutoUpdateToPatch

什么意思

频道阻止补丁级别的更改，同时保持相同的 MAJOR.MINOR.PATCH 前缀；只有后缀更改允许。

怎么办

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

频道设置

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

cannotUpdateViaPrivateChannel

什么意思

设备尝试自我关联到一个不允许设备自我分配的私有频道（allow_device_self_set is false）且该频道不是公共频道。

解决方案

启用 allow_device_self_set 在频道上启用或切换设备到公共或允许的频道。

channelMisconfigured

什么意思

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

解决方案

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

NoChannelOrOverride

什么意思

没有配置默认通道，设备也没有Channel Override

怎么办

在控制台中设置默认通道或在构建中配置 defaultChannel 分发和加密

分发和加密

Backend refusals when Capgo cannot serve or decrypt the bundle.

cannotGetBundle

__CAPGO_KEEP_0__无法生成有效的签名下载URL，没有可用清单回退

Capgo failed to generate a valid signed download URL and no manifest fallback was available.

需要做什么

重新上传 bundle，重新生成清单，验证 R2 或公共 bundle 设置。

missingBundle

是什么意思

分配给频道的 bundle 没有可下载的内容：没有 external_url,没有 r2_path,不是内置版本，和没有清单条目。

需要做什么

重新构建并重新上传版本，然后确认 bundle 有实际文件内容。

keyMismatch

是什么意思

设备加密公钥与用来加密 bundle 的密钥不匹配。元数据可能包含 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

设备状态检查

Section titled “get”

get

__CAPGO_KEEP_0__ 向设备发送新版本下载信息

Capgo sent download information for a new version to the device.

set

Section titled “set_fail”

设备激活失败

set_fail

什么是它

设备上未能激活一个包。

如何处理

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

reset

设备重置为内置包。

标题为“删除”

delete

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

下载和安装失败

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

download_0

说明

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

download_10

说明

下载了一个新的捆绑包 — 进度指示为10%

download_20

说明

下载了一个新的捆绑包 — 进度指示为20%

download_30

说明

下载进度已达到 30%

download_40

下载进度已达到 40%

说明

download_50

说明

下载进度已达到 60%

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

是什么意思

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

解决方法

Call notifyAppReady() 在应用程序启动完成后 notifyAppReady was not called, roll back current bundle maps to this code.

checksum_fail

标题：checksum_fail

The downloaded bundle failed checksum validation. Common causes: CRC32 vs SHA256 mismatch from an old CLI upload, or encryption key mismatch on older plugins that surface decryption failure as checksum failure.

下载的包校验和验证失败。常见原因：CRC32与SHA256不符的旧 __CAPGO_KEEP_0__ 上传，或者使用加密的插件出现解密失败后表现为校验和失败的加密密钥不符

Re-upload with a current CLI/plugin (SHA256). If using encryption, verify the app public key matches the upload key, or upgrade to plugin 8.3.0+ for explicit keyMismatch 重新上传一个当前 __CAPGO_KEEP_0__/插件（SHA256）。如果使用加密，请验证应用程序的公钥是否与上传密钥匹配，或者升级到插件8.3.0+以显示明确的错误。

decrypt_fail

解释

下载的包裹无法解密。

解决方法

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

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

What it means

系统杀死了应用程序，因为它占用了过多的资源。

What to do

检查元数据以获取资源类型或平台原因。

app_initialization_failure

What it means

更新器或启动器在正常运行时间之前失败了。

What to do

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

app_memory_warning

What it means

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

什么意思

The device queried its current channel.

setChannel

What it means

A channel was set successfully for the device.

uninstall

What it means

The app was uninstalled or Capgo data was cleared.

Bundle status

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

选择下载容器… 将下载并导出文件系统的快照，作为一个可浏览的 .xcappdata 文件。

右键点击此文件并选择 Show Package Contents 以打开文件夹。

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

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

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

并且 documents/versions 用于热重载

Android

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

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

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

你知道吗?

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

理解 iOS 生产崩溃日志

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

继续 Debugging

Debugging 以规划原生插件工作，连接它与 使用 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updater 使用 @capgo/capacitor-updater for the native capability in Using @capgo/capacitor-updater, 在 Capgo 插件目录 for the product workflow in Capgo Plugin Directory, Capacitor 插件由 Capgo 提供 了解 Capacitor 插件由 Capgo 提供的实现细节 添加或更新插件 了解添加或更新插件的实现细节 Ionic 企业插件替代方案 了解 Ionic 企业插件替代方案的产品工作流程