跳过内容
Capgo - Capgo Live Updates for Capacitor 应用 Capgo

Troubleshooting

Here are some common issues you might encounter while using Capgo and how to resolve them.

🚀 需要专家帮助?

遇到复杂问题？我们的专家团队在等待您！获取个人化支持、code 评估和针对您的具体需求的定制解决方案。

上传失败

上传失败

如果您的打包上传失败，请检查以下内容：

  • 您的应用 ID 是否与 __CAPGO_KEEP_0__ 控制台中的应用 ID 匹配 capacitor.config.ts 您是否从 Capgo 项目根目录运行上传命令
  • You’re running the upload command from the root of your Capacitor project
  • __CAPGO_KEEP_0__

高级上传选项

高级上传选项

Capgo CLI 提供了一些额外的标志来帮助解决常见的上传问题:

  • --tus: 使用 tus 可恢复上传协议 用于大型捆绑包或网络连接不稳定的可靠上传。如果您的捆绑包超过 10MB 或您位于一个信号不稳定的连接上，请考虑使用 --tus:

    终端窗口
    npx @capgo/cli@latest bundle upload --tus

  • --package-json 和 --node-modules: 告诉 Capgo 在哪里找到您的根 package.json 和 node_modules : 如果您的应用程序使用非标准结构，如单元测试或 npm 工作区，请传递根路径 package.json 并且 --node_modules 路径：

    终端窗口
    npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

    Capgo 需要这些信息来正确打包您的应用程序依赖项。

您可以将这些标志与其他选项结合使用，如 --channel 根据需要。请参阅 Capgo CLI 文档 以获取有关可用上传选项的详细信息。

如果您仍然遇到上传问题，请联系 Capgo 支持 以获取进一步的帮助。

调试更新

调试更新

如果您遇到与实时更新相关的问题，Capgo调试命令是一个有助于调试的工具。要使用它，请遵循以下步骤：

  1. 在项目目录中运行以下命令：

    终端窗口
    npx @capgo/cli@latest app debug

  2. 在设备或模拟器上启动应用程序并执行触发更新的操作（例如重新打开应用程序后上传新包）。

  3. 观察调试命令的输出。它将记录有关更新过程的信息，包括：

    • 应用程序检查更新时
    • 是否找到更新以及它是什么版本
    • 更新下载和安装进度
    • 更新过程中发生的任何错误

  4. 使用调试日志来确定问题的发生位置。例如：

    • 如果找不到更新，请检查您的捆绑包是否已成功上传，并确保应用程序已配置为使用正确的频道。
    • 如果更新下载但未安装，请确保您已调用 CapacitorUpdater.notifyAppReady() 并且应用程序已完全关闭并重新打开。
    • 如果您看到错误消息，请查阅Capgo文档或联系支持团队获取帮助。

调试命令特别适合于识别更新下载和安装过程中的问题。如果日志显示预期的更新版本已找到但最终未应用，重点关注下载后的步骤进行排查。

调试原生日志

原生日志调试

除了Capgo调试命令外，Android、iOS和Electron的原生日志可以提供有价值的排查信息，尤其是针对原生更新过程中的问题。

Android日志

访问Android日志：

android

  1. 连接您的设备或启动模拟器
  2. 打开 Android Studio 并选择“视图 > 工具窗口 > Logcat”
  3. 在 Logcat 窗口中，过滤日志以仅显示您的应用程序进程，请从顶部下拉菜单中选择它
  4. 寻找包含 Capgo 找到 SDK 日志

或者，您可以使用 adb logcat 命令并使用 grep 过滤日志以查找 Capgo __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 将在更新过程中记录键事件，例如:

The Capgo SDK will log key events during the update process, such as:

  • 如果发现更新并且是什么版本
  • 当更新下载开始和完成时
  • __CAPGO_KEEP_1__
  • 当更新安装被触发时
  • 在本地更新步骤中发生的任何错误

在日志中可能出现的常见 Android 特定问题包括:

  • 网络连接问题阻止更新下载
  • 保存或读取更新包时的文件权限错误
  • 更新包没有足够的存储空间
  • 更新安装后无法重启应用

iOS 日志

标题：iOS 日志

要访问 iOS 日志，请执行以下步骤:

  1. 连接您的设备或启动模拟器
  2. 在 Xcode 中打开“窗口 > 设备和模拟器”
  3. 选择您的设备并点击“打开控制台”
  4. 在控制台输出中，寻找任何包含 Capgo 来找到SDK日志

您也可以使用 log stream 命令在终端中，并使用grep过滤 Capgo 类似于Android，__CAPGO_KEEP_0__ __CAPGO_KEEP_1__将记录iOS侧的关键事件:

Similar to Android, the Capgo SDK will log key iOS-side events:

  • 下载开始、进度和完成
  • 安装触发器和结果
  • 原生更新过程中的任何错误
  • iOS特有的日志中可能包括:

iOS特有的问题

  • 下载更新时出现SSL证书问题
  • 应用程序传输安全阻止更新下载
  • 更新包装没有足够的存储空间
  • 无法正确提取或应用更新包装

Electron日志

Electron日志

对于Electron应用程序，请检查主进程和渲染器进程输出:

  1. 使用您的正常启动命令从终端运行Electron应用程序（例如 bun run electron:dev 或 bun run electron:serve并在启动、更新检查和网络错误期间监视终端输出。
  2. 在渲染器窗口中打开开发工具（视图→切换开发工具）并在重现更新流程时检查控制台日志和失败的网络请求。
  3. 对于打包的应用程序，请检查操作系统日志工具以查看崩溃或启动失败：
    • macOS: 打开 Console.app 并在应用名称上过滤
    • Windows: 打开 事件查看器 → Windows 日志 → 应用程序
    • context: 应用程序定义Linux journalctl : 使用桌面日志查看器或

When debugging updates, compare messages from both main-process and renderer-process logs to separate Electron bootstrap issues from Capgo update lifecycle issues.

Across platforms, the native logs provide a lower-level view into the update process, with more details on the native implementation. They are especially useful for identifying issues that occur outside of the Capgo JavaScript layer.

当遇到困难的实时更新问题时，捕获Capgo调试日志和原生日志是获得全面了解的好方法。两者一起会给你最大的机会识别和解决问题。

更新未应用

标题：更新未应用

如果您已上传了一个捆绑包，但在设备上却看不到任何变化：

native logs 部署实时更新 更新过程的详细指南。如果您仍然遇到问题，请使用 npx @capgo/cli@latest app debug 命令和本机日志来获取更多关于发生的事情的可见性。

常见更新失败代码

标题：常见更新失败代码

如果您的日志显示后端错误，如 disable_auto_update_to_major, semver_error或 cannot_update_via_private_channel，请使用以下专门指南：

它解释了每种常见code的含义、原因和解决方法。

SDK 安装

标题：SDK 安装

如果您遇到安装Capgo和SDK的问题，请确保：

  • 您的应用程序使用Capacitor的支持版本（4.0或更高）
  • 您遵循的步骤顺序，包括安装__CAPGO_KEEP_0__后同步您的应用程序 快速入门 steps in order, including syncing your app after installing the SDK

CI/CD集成

遇到触发__CAPGO_KEEP_0__上传的问题

检查Capgo的身份验证令牌是否设置正确

  • Double check your Capgo authentication token is set up correctly
  • 检查上传命令是否使用正确的渠道名称
  • 查看

See the CI/CD集成 查看更多的故障排除提示。您还可以使用 npx @capgo/cli@latest app debug 命令来确认您的CI/CD触发的更新是否被应用程序接收。

继续从故障排除

标题：继续从故障排除

如果您正在使用 故障排除 context:支持/高级支持页面或底部支持部分。角色：部分或页面标题。见于：页面support-policy.astro。消息键`support_policy_troubleshooting_title`（支持政策故障排除标题）。 @capgo/capacitor-data-storage-sqlite @capgo/capacitor-data-storage-sqlite 有关在@capgo/capacitor-data-storage-sqlite中实现详细信息 使用@capgo/capacitor-data-storage-sqlite @capgo/capacitor文件 查看@capgo/capacitor文件的实现细节 使用@capgo/capacitor文件 使用@capgo/capacitor文件来实现原生功能 @capgo/capacitor上传器 查看@capgo/capacitor上传器的实现细节