跳过内容
Capgo - Capacitor 应用程序的实时更新 Capgo

故障排除

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

🚀 需要专家帮助?

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

上传失败

标题为“上传失败”

如果您的捆绑包上传失败，请检查：

  • Your app ID in capacitor.config.ts 与您的应用程序在Capgo控制台中匹配
  • You’re running the upload command from the root of your Capacitor project
  • 您的Web资产已构建并且是最新的

高级上传选项

标题为“高级上传选项”的部分

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 文档 for full details on the available upload options.

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

调试更新

调试更新部分

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

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

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

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

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

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

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

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

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

调试日志

标题：调试日志

除了 Capgo debug 命令之外，Android、iOS 和 Electron 的本机日志可以提供有价值的故障排除信息，尤其是针对更新过程的本机侧问题。

Android 日志

标题：Android 日志

访问 Android 日志：

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

或者，您可以使用 adb logcat 命令并使用 grep 过滤日志 Capgo Connect your device or start your emulator

The 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 端的关键事件：

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

  • Update check initiation and result
  • 下载开始、进度和完成
  • 安装触发器和结果
  • 在原生更新过程中出现的任何错误

您在日志中可能会发现的 iOS 特定问题包括：

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

Electron 日志

标题为“Electron 日志”

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

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

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

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

当遇到棘手的实时更新问题时，捕获 Capgo debug 日志和原生日志是很好的主意。两种日志一起会给您最好的机会来识别和解决问题。

更新未应用

标题：更新未应用

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

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

参阅 实时更新部署 指南以获取有关更新过程的更多详细信息。如果您仍然卡住，请使用 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触发的更新是否被应用程序接收。

继续从故障排除

标题：继续从故障排除

如果您正在使用 故障排除 来规划存储和文件处理，连接它 @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-uploader 了解 @capgo/capacitor-uploader 的实现细节