日志
复制一个包含安装步骤和本插件的完整 Markdown 指南的设置提示.
理解应用程序日志
《理解应用程序日志》一章The Logs page provides a detailed history of update events and diagnostic information for your application. This is crucial for monitoring the update process, troubleshooting issues, and understanding how your devices interact with Capgo. You can access it by 点击您的应用 然后 点击“日志”标签（之前在一些旧的截图或文档中命名为“更新”）.
从那里您应该看到一个类似的页面，显示一个日志条目列表：
日志页面界面包括：
- 日志标签 - 日志视图的导航标签
- 刷新按钮 - 使用最新数据刷新日志列表
- 时间范围 & 动作过滤器 - 根据时间范围和动作类型过滤日志（请参见下文）
每行显示：
- 时间戳 (UTC)
- 设备 ID
- 动作 code (发生了什么)
- 版本名称 (捆绑或
builtin)
点击一行以跳转到设备详细页面查看完整历史记录。
You can filter logs by a specific time period using the date picker:
- Quick Presets - Select common time ranges: Last 1h, 3h, 6h, or 12h
- Start Time - Set a custom start time for the range
- End Time - Set a custom end time for the range
- Calendar - Pick specific dates using the calendar view
点击“选择”以应用您的选择日期范围，或者点击“取消”以关闭日历选择器。
根据操作类型过滤
标题：根据操作类型过滤您可以通过“动作”下拉菜单来过滤日志，具体到特定的事件类型：
可用的动作过滤器包括：
- 设备心跳 - 设备周期性健康检查
- 版本删除请求 - 当一个捆绑包版本被删除时
- 重置为默认版本 - 当设备恢复到内置捆绑包时
- 版本安装成功 - 捆绑包安装成功
- 新版本已发送到设备 - 当Capgo向设备发送更新时
- 版本安装失败 - 捆绑包安装失败
您可以在顶部的搜索框中快速找到特定动作类型。您可以选择多个动作以显示匹配任何选定类型的日志。
样本日志片段（假数据）
标题为“样本日志片段（假数据)”的部分| 时间（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 | 清单获取启动; SDK 即将下载文件 |
| 2025-01-14 10:00:07 | A1B2C3 | download_40 | 2.4.1 | 捆绑下载完成 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 | 捆绑安装并标记为下一次运行 |
| 2025-01-14 10:05:00 | B9C8D7 | disableAutoUpdateToMajor | 1.9.0 | 渠道策略阻止跳转到 2.x |
| 2025-01-14 10:05:05 | B9C8D7 | rateLimited | 内置 | 设备达到请求限制; SDK 等待重启 |
为了帮助您了解日志的含义，我们提供了示例序列，展示了真实设备更新的旅程：
Successful Update Flow
Section titled “Successful Update Flow”这是您的日志中健康更新的样子：
| 时间 | 设备 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 | 包已安装并激活 |
设备已最新
设备已最新设备已有最新版本：
| 时间 | 设备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 | 应用程序崩溃或 notifyAppReady() 没有成功 - 回滚触发 |
| 11:15:11 | i9j0k1l2 | reset | 内置 | 设备已恢复到内置版本 |
需要执行操作: 检查您的应用程序是否正确调用 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 | 下载失败（网络超时，连接丢失等） |
需要动作：设备将在下次应用启动时自动重试。除非出现频繁问题，否则无需采取任何行动。
计划限制已达到
标题：计划限制已达到当您的账户达到设备限制时：
| 时间 | 设备 ID | 操作 | 版本 | 这意味着什么 |
|---|---|---|---|---|
| 16:00:00 | q7r8s9t0 | needPlanUpgrade | - | 直到您升级或billing周期重置，这台设备将不会接收更新 |
需要操作: 升级您的计划 或等待下一个billing周期
渠道配置阻止更新
标题：渠道配置阻止更新当渠道设置阻止更新时：
| 时间 | 设备 ID | 操作 | 版本 | 这意味着什么 |
|---|---|---|---|---|
| 12:00:00 | u1v2w3x4 | disableAutoUpdateToMajor | 2.0.0 | 设备在 v1.x 上无法自动更新到 v2.x (版本跳转被阻止) |
| 12:05:00 | y5z6a7b8 | disableEmulator | 1.2.0 | 检测到模拟器，且渠道阻止模拟器 |
| 12:10:00 | c9d0e1f2 | disableDevBuild | 1.2.0 | 检测到开发版，且渠道阻止开发版 |
需要操作：这些是有意的保护措施。如果您想允许这些更新，修改您的 渠道设置.
日志代码 (Capgo 后端枚举)
标题：日志代码（Capgo 后端枚举）这些代码来自 stats_action 用于仪表板的枚举API（capgo/src/types/supabase.types.ts）。如果您在 UI 中看到一个新的code，它是由SDK 或后端发出的，并且已验证为此列表中的项。
Happy path & 生命周期
| Code(s) | 含义 |
|---|---|
get | 设备要求Capgo获取当前频道清单 |
download_manifest_start, download_manifest_complete | 清单下载开始/完成（对于delta或多文件包） |
download_zip_start, download_zip_complete | zip压缩包下载开始/完成 |
download_10 … download_90 | 下载进度里程碑 |
download_0 | 第一个进度事件的0%进度标记 |
download_complete | 整个捆绑包下载完成 |
set | 捆绑包已为下次启动准备 |
reset | 设备已恢复到内置捆绑包 |
delete | 捆绑包已从本地存储中移除 |
uninstall | 应用卸载检测 |
app_moved_to_foreground, app_moved_to_background | 应用生命周期事件由SDK记录 |
ping | 设备健康/心跳检查 |
setChannel, getChannel | 通道被SDK覆写或拉取 |
新政策阻断/限速快速修复
新政策阻断/限速快速修复| Code | 为什么会这样 | What to do next |
|---|---|---|
invalidIp | Capgo 检测到类似机器人流量（Google/云基础设施 IP）。 | 忽略真实用户；从真实设备和正常网络中重试，或者在一段时间后检查。 |
needPlanUpgrade | 组织已达到计划/设备限制。 | 在仪表板中升级计划或等待下一个billing周期。 |
semver_error | 本地应用程序版本在配置中丢失或无效的semver（x.y.z). | 设置 plugins.CapacitorUpdater.version 为有效的semver，然后在 SemVer 测试器 中验证它并重建应用程序。 |
disablePlatformIos | iOS 在通道策略中被禁用。 | 如果这是意外的，请在该通道中启用 iOS 并重新发布路由。如果您故意在此跟踪中阻止 iOS，则保持它关闭并将 iOS 构建移到单独的通道。 |
disablePlatformAndroid | Android在渠道策略中被禁用。 | 如果这是意外的，请在该渠道中启用Android并重新发布路由。如果您在此跟踪中故意阻止Android，请保持禁用状态并将Android构建移到单独的渠道。 |
disableAutoUpdate | 渠道自动更新模式阻止此更新风格。 | 更改渠道自动更新策略（主/次/修订/元数据/无）以允许您的意图发布。 |
disableAutoUpdateUnderNative | 渠道设置为阻止更新，更新的版本比设备基线要旧。 | 推送一个在原生基线以上的版本，或者禁用原生基线以下的保护。 |
disableAutoUpdateMetadata | 渠道要求 min_update_version 元数据和应用程序更新较旧。 | 设置 min_update_version 为目标捆绑包或发布从新原生版本中获取。 |
disableAutoUpdateToMajor | 渠道阻止主版本跳转。 | 保持主版本在同一渠道策略中，或者允许此跟踪中的主版本跳转。 |
disableAutoUpdateToMinor | 本渠道阻止了小版本跳跃. | 保持同一渠道策略中的小版本号，或者允许此条目的小版本跳跃. |
disableAutoUpdateToPatch | 本渠道阻止了此流程的补丁级别跳跃. | 调整您的发布节奏，或者在此条目中打开渠道策略中的补丁级别跳跃. |
disableEmulator | 此渠道不允许模拟器更新. | 如果这是意外的，请在测试渠道中启用模拟器更新并验证模拟器。如果这是故意的，请保持此渠道的模拟器阻塞，并在另一个渠道中使用模拟器构建. |
disableDevBuild | 此渠道阻止了开发者构建. | 如果这是意外的，请允许开发者更新或将设备移动到启用开发者更新的渠道。如果这是故意的，请保持此渠道锁定到仅发布构建. |
disableProdBuild | 在生产模式下构建的设备 /updates，而您的渠道阻止了它. | 如果这是意外的，请允许在该渠道中更新生产并重新发布。如果这是故意的，请保持限制并将生产构建发送到正确的渠道/构建. |
cannotGetBundle | Capgo无法为选定的捆绑包构建一个有效的下载URL。 | 重新上传包或重新生成清单并检查 R2/public 包设置。 |
cannotUpdateViaPrivateChannel | 应用尝试切换到不允许自我赋值的私有频道。 | 启用 allow_device_self_set 在频道上或切换到公共/允许频道。 |
channelMisconfigured | 频道自动更新规则缺少必要数据（version_number 缺少”，填补该规则的缺失配置或切换到更简单的自动更新模式。 min_update_version). | 包没有可下载的负载（缺少 |
missingBundle | 和没有清单）。 external_url/r2_path 重新构建/重新上传版本并验证包有真实文件内容。 | 没有匹配该设备的频道（没有云默认值 + 没有配置回退 + 没有覆盖）。 |
NoChannelOrOverride | 在控制台中设置频道默认值或保留测试 | Set a channel default in dashboard or keep a test defaultChannel 在该构建中. |
rateLimited | 短时间内（通常是渲染循环中）频繁更新/频道调用（ setChannel/getChannel). | 在渲染过程中不要调用。只在用户操作时调用。使用 defaultChannel 在 capacitor.config. |
keyMismatch | 应用程序和捆绑包加密密钥ID不一致（device_key_id vs bundle_key_id). | 在控制台中比较设备和捆绑包密钥ID。如果它们不一致，请使用相同的密钥和匹配的CLI/插件版本发布；密钥编码可以在版本之间不同。 |
disableDevice | 因为该频道设置为阻止真实设备，这个真实手机/平板被阻止了. | 如果是意外的，请在该频道中打开真实设备更新。如果是有意的，请保持它被阻止并将真实设备路由到另一个频道. |
disablePlatformElectron | 在本频道中，Electron被阻止了. | 如果这是意外的，请在本频道中启用Electron并重新发布路由。如果是有意的，请保持它被阻止并将Electron用户路由到一个专门的频道. |
customIdBlocked | 发送了一个自定义设备ID，但该应用程序不接受自定义ID。 | 关闭自定义 ID 发送或仅在您的工作流程需要时启用自定义 ID。 |
blocked_by_server_url | 应用已 server.url 已配置，因此 Capacitor 将使用远程 URL 代替本地文件。 | 清除 server.url 用于生产构建并保持更新包装本地。 |
backend_refusal | 更新器是 v4,后端不再接受。 | 升级插件/CLI 到 v5+ (优先 v8), with Capacitor v5配置或策略块 |
| 升级插件/__CAPGO_KEEP_0__ 到 |
| Code(s) | 更新被阻止的原因 |
|---|---|
disableAutoUpdate, disableAutoUpdateToMajor, disableAutoUpdateToMinor, disableAutoUpdateToPatch, disableAutoUpdateMetadata, disableAutoUpdateUnderNative | 渠道策略禁止此操作 版本号跳跃 |
disablePlatformIos, disablePlatformAndroid | 在此渠道中，平台已被禁用 |
disableDevBuild, disableEmulator | 开发版或模拟器不允许 |
disableProdBuild, disableDevice, disablePlatformElectron | 此渠道下生产版、真实设备或Electron均被阻止 |
customIdBlocked | 自定义设备ID不被此应用接受 |
cannotUpdateViaPrivateChannel, NoChannelOrOverride, channelMisconfigured | 渠道选择或覆盖失败 |
missingBundle, cannotGetBundle | 清单指向一个Capgo无法提供的包 |
needPlanUpgrade | 组织已达到计划/设备限制 |
rateLimited | 请求过多，SDK将在重启后解除限制 |
blocked_by_server_url, backend_refusal, invalidIp | 服务器端规则阻止了请求 |
下载 / 整合 / 安装失败
| Code(s) | 含义 |
|---|---|
download_fail | bundle下载失败（网络或响应错误） |
download_manifest_file_fail, download_manifest_checksum_fail, download_manifest_brotli_fail | 无法获取或验证清单文件 |
checksum_fail, checksum_required | 完整性检查失败或校验和丢失 |
unzip_fail, directory_path_fail, canonical_path_fail, windows_path_fail | 文件系统或解压验证失败 |
decrypt_fail | 解密失败（加密的bundle） |
update_fail | bundle安装成功但应用程序从未调用 notifyAppReady(); 回滚触发 |
download_zip_* 无后续 set | 下载完成但安装阶段永远未完成 |
运行时/平台事件
标题：运行时/平台事件| Code(s) | 含义 |
|---|---|
app_crash, app_crash_native | JavaScript 或原生运行时层面上的崩溃事件。元数据通常包含堆栈、源码和活跃版本信息。 |
app_anr | Android 报告了应用未响应的事件 |
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 包行为区分开来 |
➡️需要更深入的每个code指南？请参见 全日志Code参考和调试指南.
获取有关日志的更多详细信息
标题为“获取有关日志的更多详细信息”如果您点击特定日志条目，它通常会将您带到 设备页面。这使您可以看到该设备的完整历史记录，这对于诊断设备特定的问题或了解其更新旅程非常有帮助。
从日志中继续
标题为“从日志中继续”如果您正在使用 日志 来规划仪表板和API操作，连接它与 API概览 关于API的实现细节 简介 关于Introduction的实现细节 API密钥 关于API Keys的实现细节 设备 关于Devices的实现细节 捆绑包 关于Bundles的实现细节