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

故障排除

使用 Capgo 时可能遇到的常见问题和解决方法。

🚀 需要专家帮助?

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

上传失败

标题：上传失败

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

  • 您的应用 ID 与 __CAPGO_KEEP_0__ 控制台中的应用 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 资产已构建并且是最新的

高级上传选项

高级上传选项

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

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

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

  • --package-json : 告诉 __CAPGO_KEEP_0__ 其根目录的位置 --node-modules: Tells Capgo where to find your root package.json 如果您的应用程序使用非标准结构，如 monorepo 或__CAPGO_KEEP_0__工作区。将根目录的路径传递给 node_modules if your app uses a non-standard structure like a monorepo or npm workspace. Pass the path to the root package.json 路径： --node_modules 终端窗口

    复制到剪贴板
    npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

    Capgo needs this information to correctly bundle your app’s dependencies.

如所需。请参阅 --channel __CAPGO_KEEP_0__ __CAPGO_KEEP_1__文档 Capgo CLI docs 如果您仍然遇到上传问题，请联系我们

如果您的应用程序使用非标准结构，如 monorepo 或__CAPGO_KEEP_0__工作区。将根目录的路径传递给 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特定问题包括：

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

Electron日志

标题为“Electron日志”

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

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

当调试更新时，比较主进程和渲染进程日志中的消息，以区分 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 集成

__CAPGO_KEEP_0__ 上传触发问题

双重检查您的 Capgo 身份验证令牌设置正确

  • Double check your Capgo authentication token is set up correctly
  • __CAPGO_KEEP_1__
  • 检查上传命令是否使用了正确的渠道名称来适应目标环境

查看 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。