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

故障排除

以下是您可能遇到的使用 Capgo 时遇到的常见问题及其解决方案。

🚀 需要专家帮助？

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

上传失败

上传失败

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

  • 您的应用 ID 是否与 __CAPGO_KEEP_0__ 控制台中的应用 ID 匹配 capacitor.config.ts 您是否从您的 Capgo 项目根目录运行上传命令
  • 您正在从您的Capacitor项目根目录运行上传命令
  • matches your app in the Capgo dashboard

高级上传选项

高级上传选项

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

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

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

  • --package-json 和 --node-modules: 告诉 Capgo 根目录的位置 package.json 和 node_modules 如果您的应用使用非标准结构，如 monorepo 或 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 支持 获取进一步的帮助。

调试更新

Debugging Updates

如果您遇到与实时更新相关的问题，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__将在更新过程中记录键事件，例如:

Capgo SDK 会在更新过程中记录键盘事件，例如：

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

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

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

iOS 日志

标题：iOS 日志

访问 iOS 日志的方法：

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

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

iOS设备上，Capgo SDK 会记录关键事件。

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

在终端中使用

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

Electron 日志

Electron 日志

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

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

当调试更新时，比较主进程和渲染进程日志中的消息，以区分 Electron 引导问题和 Capgo 更新生命周期问题。

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.

When troubleshooting a tricky live update problem, it’s a good idea to capture both the Capgo debug logs and the native logs for a comprehensive picture of what’s happening. The two logs together will give you the best chance of identifying and resolving the issue.

更新未应用

标题：更新未应用

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

  • 确保在您的应用中调用 CapacitorUpdater.notifyAppReady() 在您的应用程序中code，如图所示。 quickstart
  • 检查您的设备是否已连接到互联网，并确保Capgo调试日志显示更新已下载。
  • 查找原生日志中的任何错误，这可能指示更新应用问题
  • 参见

Section titled “Updates not applying” 部署实时更新 实时更新的详细指南。如果您仍然遇到问题，请使用 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.
  • 检查上传命令是否使用正确的渠道名称
  • 查看

快速入门步骤 CI/CD集成 查看更多的故障排除技巧。您也可以使用命令来确认您的CI/CD触发的更新是否被应用程序接收。 npx @capgo/cli@latest app debug 继续从故障排除

继续从故障排除

如果您正在使用

故障排除 用于规划存储和文件处理，连接它与 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-data-storage-sqlite 有关在@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上传器中的实现细节