跳过内容
Capgo - Capgo 实时更新的 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提供一些额外的标志来帮助解决常见的上传问题： 分段上传协议 为了更可靠地上传大型包或在网络连接不稳定的情况下。如果您的包大小超过 10MB 或您正在使用不稳定的网络连接，考虑使用 --tus:

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

  • --package-json 并且 --node-modules: 告诉 Capgo 根目录的位置 package.json 和 node_modules 如果您的应用程序使用非标准结构，如 monorepo 或 npm 工作区。 请将根目录的路径传递给 CLI。 package.json 和 --node_modules path:

    终端窗口
    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文档或联系支持团队以获取帮助。

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

Native 日志调试

标题：Native 日志调试

除了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:

  • 如果发现更新并显示版本号
  • 更新下载开始和完成时
  • 触发更新安装时
  • 在本地更新步骤中发生的任何错误
  • 您在日志中可能会看到的常见 Android 特定问题包括：

网络连接问题阻止更新下载

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

iOS 日志

iOS 日志

要访问 iOS 日志：

  1. 连接您的设备或启动模拟器
  2. 在 Xcode 中打开“窗口 > 设备和模拟器”
  3. 选择您的设备并单击“打开控制台”
  4. 在控制台输出中查找包含 __CAPGO_KEEP_0__ 的行 Capgo to find the SDK logs

您也可以使用 log stream 命令在终端中输入并使用grep查找 Capgo 过滤日志。

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

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

iOS 相关问题可能在日志中被识别出来：

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

electron 日志

Electron 日志

在 Electron 应用程序中，检查主进程和渲染进程的输出：

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

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

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

在调试一个棘手的实时更新问题时，捕获 Capgo debug 日志和native 日志是有益的。两者一起会给您提供最好的机会来识别和解决问题。

更新未应用

标题为“更新未应用”

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

  • 确保您已在应用中调用 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集成

与CI/CD管道触发Capgo上传相关的问题：

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

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