跳过内容
Capgo - Capgo 实时更新 for Capacitor 应用 Capgo

故障排除

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

🚀 需要专家帮助?

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

上传失败

上传失败

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

  • 您的应用 ID capacitor.config.ts matches your app in the Capgo dashboard
  • You’re running the upload command from the root of your Capacitor project
  • 您的 Web 资产已构建并且是最新的

高级上传选项

高级上传选项

The Capgo CLI provides some additional flags to help with common upload issues:

  • --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 支持 获取进一步的帮助。

调试更新

标题为“调试更新”

如果您遇到实时更新问题，Capgo调试命令是一个有用的工具来进行故障排除。要使用它：

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

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

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

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

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

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

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

The debug command is especially useful for identifying issues with the update download and installation process. If the logs show the expected update version was found but not ultimately applied, focus your troubleshooting on the steps after the download.

调试原生日志

Section titled “调试原生日志”

In addition to the Capgo debug command, the native logs on Android, iOS, and Electron can provide valuable troubleshooting information, especially for issues on the native side of the update process.

Android 日志

Section titled “Android 日志”

To access the Android logs:

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

您也可以使用 adb logcat 命令并使用grep过滤 Capgo 来过滤日志。

在更新过程中，Capgo SDK 将记录以下关键事件：

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

您在日志中可能会看到的常见Android特定问题包括：

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

iOS 日志

iOS 日志

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

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

您还可以使用 log stream 命令在终端中查找 Capgo 过滤日志。

与 Android 类似，Capgo SDK 将记录 iOS 端的关键事件：

  • 更新检查启动和结果
  • 下载开始、进度和完成
  • 安装触发器和结果
  • 在本地更新过程中出现的任何错误

在日志中可能遇到的 iOS 特定问题包括：

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

Electron 日志

Electron 日志

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

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

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

跨平台，原生日志提供了一个更低级别的更新过程视图，原生实现的更多详细信息。它们特别适合于识别发生在 Capgo JavaScript 层之外的问题。

当遇到棘手的实时更新问题时，捕获 Capgo debug 日志和原生日志是有益的。两者一起会给您提供最全面的了解，帮助您识别和解决问题。

更新未应用

标题：更新未应用

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

  • 确保您已在应用程序中调用 CapacitorUpdater.notifyAppReady() 在您的应用程序中 code 如下所示 快速入门
  • 检查您的设备是否已连接到互联网，并且 Capgo debug 日志显示更新已下载
  • 尝试完全关闭并重新打开应用程序，因为更新仅在新启动时应用
  • 查找任何可能指示更新应用过程中出现问题的本机日志错误

参阅 部署实时更新 指南以获取有关更新过程的更多详细信息。如果您仍然卡住，请使用 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或更高）
  • 您遵循了 快速入门 步骤的顺序，包括安装SDK后同步您的应用程序

CI/CD 集成

CI/CD 集成

如果您遇到触发Capgo上传的CI/CD管道问题：

  • 请检查您的Capgo身份验证令牌是否设置正确
  • 确保在构建Web资产后运行上传命令
  • 检查上传命令是否使用正确的渠道名称

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

继续Troubleshooting

继续Troubleshooting

如果您正在使用 故障排除 为计划存储和文件处理，连接它与 @capgo/capacitor-data-storage-sqlite 在 @capgo/capacitor-data-storage-sqlite 中的实现细节中 使用 @capgo/capacitor-data-storage-sqlite 为 @capgo/capacitor-data-storage-sqlite 的本机功能 @capgo/capacitor-file 在 @capgo/capacitor-file 中的实现细节中 使用 @capgo/capacitor-file 为 @capgo/capacitor-file 的本机功能 在使用 @capgo/capacitor-file 的同时，和 对于 @capgo/capacitor-uploader 的实现细节。