日志
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
日志与日志洞察
标题为“日志与日志洞察”的章节应用 日志 标签页默认打开。 日志洞察 使用 Insights 按类别、版本和设备确定优先级，时间范围可选 1、3、7 或 30 天。请切换到 日志 子标签页，查看下文所述的底层设备事件、过滤器和时间戳。
了解应用日志
章节标题：“了解应用日志”Raw Logs 子标签页提供了应用更新事件的详细历史记录和诊断信息。它有助于确认 Insight 背后的设备端证据、排查更新路径问题，并了解设备如何与 Capgo 进行交互。打开应用，选择 日志，然后选择 日志 子标签页。
Raw Logs 界面包含：
- Logs 子标签页 — 用于单个日志行的导航控件。
- 刷新按钮 — 使用最新数据刷新日志列表。
- 时间范围与操作过滤器 — 按时间和操作筛选事件流。
每行显示：
- 时间戳 (UTC)
- 设备 ID
- 操作 code (发生了什么)
- 版本名称 (bundle 或
builtin)
点击行即可跳转至设备详情页，查看完整历史记录。
按日期范围筛选
标题为“按日期范围筛选”的章节您可以使用日期选择器按特定时间段筛选日志：
- 快速预设 - 选择常用时间范围：最近 1h、3h、6h 或 12h
- 开始时间 - 为该范围设置自定义开始时间
- 结束时间 - 为该范围设置自定义结束时间
- 日历 - 通过日历视图选择特定日期
点击 “Select” 应用所选日期范围，或点击 “Cancel” 关闭选择器。
通过 Actions 下拉菜单，您可以按特定事件类型筛选日志：
可用的 Action 过滤器包括：
- 设备心跳 - 来自设备的定期健康检查
- 已请求删除版本 - 当某个 bundle 版本被删除时
- 重置为默认版本 - 当设备回退到内置 bundle 时
- 版本安装成功 - bundle 安装成功
- 新版本已发送至设备 - 当 Capgo 向设备发送更新时
- 版本安装失败 - 当 bundle 安装失败时
使用顶部的搜索框快速查找特定的操作类型。您可以选择多个类型，以显示匹配其中任何类型的日志。
日志片段示例 (模拟数据)
标题为“日志片段示例（模拟数据）”的部分| 时间 (UTC) | 设备 ID | 操作 | 版本 | 含义说明 |
|---|---|---|---|---|
| 2025-01-14 10:00:01 | A1B2C3 | get | 2.4.1 | 设备向 Capgo 查询是否有可用更新 |
| 2025-01-14 10:00:03 | A1B2C3 | download_manifest_start | 2.4.1 | 已启动 Delta 下载；SDK 即将下载变更的 delta 文件 |
| 2025-01-14 10:00:07 | A1B2C3 | download_40 | 2.4.1 | Bundle 下载进度 40% |
| 2025-01-14 10:00:12 | A1B2C3 | download_zip_complete | 2.4.1 | Zip 下载完成 |
| 2025-01-14 10:00:13 | A1B2C3 | set | 2.4.1 | Bundle 已安装并标记为下次运行版本 |
| 2025-01-14 10:05:00 | B9C8D7 | disableAutoUpdateToMajor | 1.9.0 | Channel 策略阻止了向 2.x 版本的跳转 |
| 2025-01-14 10:05:05 | B9C8D7 | rateLimited | 内置 | 设备达到请求上限；SDK 将退避，直到重启 |
日志场景示例
标题为“示例日志场景”的部分为了帮助您理解日志含义，以下是展示真实设备更新流程的示例序列：
更新成功流程
标题为“成功更新流程”的部分日志中一次正常的更新是这样的：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 10:00:01 | a1b2c3d4 | get | 1.2.0 | 设备已检查更新，并获取到版本 1.2.0 信息 |
| 10:00:02 | a1b2c3d4 | download_10 | 1.2.0 | 开始下载，已完成 10% |
| 10:00:03 | a1b2c3d4 | download_50 | 1.2.0 | 下载进度 50% |
| 10:00:05 | a1b2c3d4 | download_complete | 1.2.0 | 下载成功 |
| 10:00:06 | a1b2c3d4 | set | 1.2.0 | Bundle 已安装并激活 |
设备已是最新版本
标题为“设备已是最新版本”当设备检查更新但已是最新版本时：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 14:30:00 | e5f6g7h8 | noNew | 1.2.0 | 设备已是最新版本，无需更新 |
更新失败并回滚
标题为“更新失败并回滚”的章节当更新失败且设备执行回滚时：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 11:15:00 | i9j0k1l2 | get | 1.3.0 | 设备已收到更新信息 |
| 11:15:02 | i9j0k1l2 | download_complete | 1.3.0 | 下载完成 |
| 11:15:03 | i9j0k1l2 | set | 1.3.0 | Bundle 已设置 |
| 11:15:10 | i9j0k1l2 | update_fail | 1.3.0 | App 崩溃或 notifyAppReady() 未被调用 - 已触发回滚 |
| 11:15:11 | i9j0k1l2 | reset | 内置 | 设备已回退到内置版本 |
需采取的操作: 请检查你的 App 是否调用了 notifyAppReady() 在初始化成功后。请参阅 插件文档 详情。
下载失败
“下载失败”章节当网络问题导致下载失败时：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 09:45:00 | m3n4o5p6 | get | 1.2.0 | 设备已收到更新信息 |
| 09:45:01 | m3n4o5p6 | download_30 | 1.2.0 | 下载已开始，但…… |
| 09:45:15 | m3n4o5p6 | download_fail | 1.2.0 | 下载失败（网络超时、连接中断等） |
需采取的操作：设备将在下次启动 App 时自动重试。除非此类情况频繁发生，否则无需手动操作。
达到套餐限制
标题为“已达到套餐限制”的章节当您的账号达到设备上限时：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 16:00:00 | q7r8s9t0 | needPlanUpgrade | - | 在您升级套餐或计费周期重置前，此设备将无法接收更新 |
需采取的操作: 升级套餐 或等待下一个计费周期。
Channel 配置阻止更新
“Channel 配置阻止更新”章节当 Channel 设置阻止更新时：
| 时间 | 设备 ID | 操作 | 版本 | 含义 |
|---|---|---|---|---|
| 12:00:00 | u1v2w3x4 | disableAutoUpdateToMajor | 2.0.0 | 设备处于 v1.x，无法自动更新到 v2.x（大版本升级被阻止） |
| 12:05:00 | y5z6a7b8 | disableEmulator | 1.2.0 | 检测到模拟器，且 Channel 禁止模拟器 |
| 12:10:00 | c9d0e1f2 | disableDevBuild | 1.2.0 | 检测到 Dev build，且 Channel 禁止 Dev build |
需采取的操作: 这些是有意设置的保护机制。如果你想允许这些更新，请修改你的 频道设置.
日志代码 (Capgo 后端枚举)
标题为“日志代码 (Capgo 后端枚举)”的部分这些代码源自 stats_action dashboard 使用的枚举 API (capgo/src/types/supabase.types.ts)。如果在 UI 中看到新的 code，则该代码由 SDK 或后端发出，并根据此列表进行了校验。
正常流程与生命周期
| Code(s) | 含义 |
|---|---|
get | 设备向 Capgo 请求与其频道关联的 bundle |
download_manifest_start, download_manifest_complete | Delta 下载开始 / 完成（适用于使用 delta 文件上传的 bundle） |
download_zip_start, download_zip_complete | Zip 压缩包下载开始 / 完成 |
download_10 … download_90 | 下载进度里程碑 |
download_0 | 首次进度事件的 0% 标记 |
download_complete | 整个 bundle 已下载完成 |
set | bundle 已就绪，等待下次启动 |
reset | 设备已回退至内置 bundle |
delete | bundle 已从本地存储中移除 |
uninstall | 检测到 App 已卸载 |
app_moved_to_foreground, app_moved_to_background | 由 SDK 记录的 App 生命周期事件 |
ping | 来自设备的健康检查/心跳检测 |
setChannel, getChannel | 通过 SDK 调用覆盖或获取了 Channel |
新策略拦截 / 限流快速修复
标题为“新策略拦截/节流快速修复”的部分| Code | 为什么会这样 | 接下来怎么做 |
|---|---|---|
invalidIp | Capgo 检测到疑似机器人流量（Google/云基础设施 IP）。 | 真实用户可忽略；请用真实设备和正常网络重试，或稍后再检查。 |
needPlanUpgrade | 组织已达到套餐/设备上限。 | 在 dashboard 中升级套餐，或等待下个计费周期。 |
semver_error | 配置中的原生 app 版本缺失或 semver 无效（x.y.z). | 设置 plugins.CapacitorUpdater.version 请改为有效的 semver，然后在 SemVer 测试器 中进行验证，并重新构建 app。 |
disablePlatformIos | Channel 策略中已禁用 iOS。 | 如果这是误操作，请在该 Channel 中启用 iOS 并重新发布 routing。如果你有意在此 track 中屏蔽 iOS，请保持关闭，并将 iOS build 移到单独的 Channel。 |
disablePlatformAndroid | Channel 策略中已禁用 Android。 | 如果这是误操作，请在该 Channel 中启用 Android 并重新发布 routing。如果你有意在此 track 中屏蔽 Android，请保持关闭，并将 Android build 移到单独的 Channel。 |
disableAutoUpdate | Channel 的自动更新模式不允许这种更新方式。 | 请更改 Channel 的自动更新策略（major/minor/patch/metadata/none），以允许你计划的 rollout。 |
disableAutoUpdateUnderNative | 该 Channel 已设置为阻止低于设备基线的更新。 | 请推送等于或高于 Native 基线的版本，或禁用该低于 Native 版本的保护。 |
disableAutoUpdateMetadata | Channel 要求 min_update_version metadata，且 App 版本较旧。 | 设置 min_update_version 目标 bundle 或 release 需来自更新的 Native 版本。 |
disableAutoUpdateToMajor | 该 Channel 会拦截大版本跳跃。 | 将大版本保持在同一 Channel 策略中，或允许此 Track 进行大版本跳跃。 |
disableAutoUpdateToMinor | 该 Channel 会拦截小版本跳跃。 | 将小版本保持在同一 Channel 策略中，或允许此 Track 进行小版本跳跃。 |
disableAutoUpdateToPatch | 该流程的 Channel 会拦截补丁版本跳跃。 | 请对齐您的发布节奏，或在 Channel 策略中允许此 Track 进行补丁跳跃。 |
disableEmulator | 此 Channel 不允许 Emulator 更新。 | 如果这是误操作，请在用于验证 Emulator 的测试 Channel 中开启 Emulator 更新。如果是刻意为之，请保持此 Channel 拦截 Emulator，并使用其他 Channel 进行 Emulator 构建。 |
disableDevBuild | 此 Channel 已拦截 Dev 构建。 | 如果这是误操作，请允许 Dev 更新或将设备移至已启用 Dev 的 Channel。如果是刻意为之，请保持此 Channel 仅锁定用于 Release 构建。 |
disableProdBuild | 检测到处于生产模式的设备构建名为 /updates，但您的 Channel 已将其拦截。 | 如果这是误操作，请在该 channel 允许 production 更新并重新发布。如果是刻意为之，请保留该限制，并将 production build 发送到正确的 channel/build。 |
cannotGetBundle | Capgo 无法为所选 bundle 构建有效的下载 URL。 | 请重新 upload bundle（如果 --delta 需要 delta 文件），并检查 R2/public bundle 设置。 |
cannotUpdateViaPrivateChannel | App 尝试自动切换到不允许 self-assignment 的 private channel。 | 启用 allow_device_self_set 在该 channel 上，或切换到 public/允许的 channel。 |
channelMisconfigured | Channel auto-update 规则缺少必要数据（version_number 无需 min_update_version). | 请完善该规则缺失的配置，或切换到更简单的 auto-update 模式。 |
missingBundle | Bundle 没有可下载的 payload（缺少 external_url/r2_path 且没有 delta 文件）。 | 重新构建/重新上传该版本，并验证 bundle 是否包含实际文件内容。 |
NoChannelOrOverride | 未找到匹配此设备的 channel（无云端默认值 + 无配置回退 + 无覆盖设置）。 | 在 dashboard 中设置 channel 默认值，或保留一个测试 channel defaultChannel 在该 build 中。 |
rateLimited | 短时间内 update/channel 调用过多（常见于 render 循环） setChannel/getChannel). | 不要在 render 中调用。仅在用户操作时调用。请使用 defaultChannel 中的 capacitor.config. |
keyMismatch | App 与 bundle 的加密 key ID 不一致（device_key_id 对比 bundle_key_id). | 在控制台中对比设备和 bundle 的 key ID。如果不同，请使用相同的 key 和匹配的 CLI/plugin 版本发布；不同版本的 key 编码可能不同。 |
disableDevice | 真实手机/平板被拦截，因为该 channel 已设置为拦截真实设备。 | 如果是误操作，请在该 channel 中开启真实设备更新。如果是有意为之，请保持拦截，并将真实设备路由到其他 channel。 |
disablePlatformElectron | 此频道已禁用 Electron。 | 如果这是误操作，请在此频道启用 Electron 并重新发布路由。如果是刻意为之，请保持禁用状态，并将 Electron 用户引导至专用频道。 |
customIdBlocked | 已发送自定义设备 ID，但此应用不接受自定义 ID。 | 请关闭自定义 ID 发送功能，或者仅在工作流确实需要时才启用自定义 ID。 |
blocked_by_server_url | 应用已 server.url 配置，因此 Capacitor 将提供远程 URL 而非本地文件。 | 移除/清除 server.url 用于生产环境构建，并保持更新包为本地文件。 |
backend_refusal | 更新程序版本为 v4，后端已不再支持该版本。 | 请将 plugin/CLI 升级至 v5+ (建议使用 v8), 以及 Capacitor v5+，然后重新构建并发布 bundle 元数据。 |
| 配置或策略拦截 |
| Code(s) | 更新被拦截的原因 |
|---|---|
disableAutoUpdate, disableAutoUpdateToMajor, disableAutoUpdateToMinor, disableAutoUpdateToPatch, disableAutoUpdateMetadata, disableAutoUpdateUnderNative | Channel 策略禁止此操作 semver 跳变 |
disablePlatformIos, disablePlatformAndroid | 该 Channel 已禁用此平台 |
disableDevBuild, disableEmulator | 不允许使用 Dev build 或模拟器 |
disableProdBuild, disableDevice, disablePlatformElectron | 此 Channel 禁止使用 Production build、真机或 Electron。 |
customIdBlocked | 此 App 不接受自定义设备 ID。 |
cannotUpdateViaPrivateChannel, NoChannelOrOverride, channelMisconfigured | Channel 选择或覆盖失败 |
missingBundle, cannotGetBundle | 该 Channel 指向了 Capgo 无法提供的 Bundle |
needPlanUpgrade | 组织已达到套餐/设备上限 |
下载 / 完整性 / 安装失败
| Code(s) | 含义 |
|---|---|
download_fail | Bundle 下载失败 (网络或响应错误) |
download_manifest_file_fail, download_manifest_checksum_fail, download_manifest_brotli_fail | 无法获取或校验 Delta 文件 |
checksum_fail, checksum_required | 完整性校验失败或校验和缺失 |
unzip_fail, directory_path_fail, canonical_path_fail, windows_path_fail | 文件系统或解压校验失败 |
decrypt_fail | 解密失败 (加密 Bundle) |
update_fail | Bundle 已安装但 App 未调用 notifyAppReady()；已触发回滚 |
download_zip_* 无后续 set | 下载完成，但安装阶段始终未完成 |
运行时 / 平台事件
标题为“运行时 / 平台事件”的章节| Code(s) | 含义 |
|---|---|
app_crash, app_crash_native | 来自 JavaScript 或原生运行时层的崩溃事件。元数据通常包含堆栈、来源和当前活跃版本信息。 |
app_anr | Android 报告应用无响应 (ANR)。 |
app_killed_low_memory, app_killed_excessive_resource_usage | 应用进程因内存或资源限制而终止。 |
app_initialization_failure, app_memory_warning | 启动被中断，或在进入正常运行前出现内存压力。 |
webview_javascript_error, webview_unhandled_rejection, webview_resource_error, webview_security_policy_violation, webview_unclean_restart, webview_render_process_gone, webview_content_process_terminated | WebView 生命周期及 JS/渲染错误。在 JS 和原生层都安装 Sentry，以捕获堆栈跟踪、会话/设备上下文和 URL/状态，从而更快修复问题。 |
os_version_changed, native_app_version_changed | 操作系统或原生应用版本发生变化；这有助于区分平台层面的发布影响与 Web bundle 行为。 |
➡️ 需要更深入的 code 指南？请参阅 完整的 Code 日志参考与调试指南.
获取单条日志的更多详情
标题为“获取更多日志详情”的部分点击特定的日志条目，通常会跳转到 设备的页面。通过该页面，你可以查看该设备的完整历史记录，这对于诊断特定设备的问题或了解其更新历程非常有帮助。
继续探索日志
标题为“从日志继续操作”的部分如果你正在使用 日志 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。
