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

故障排除

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

🚀 需要专家帮助?

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

上传失败

标题：上传失败

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

  • 您的应用 ID 与 __CAPGO_KEEP_0__ 控制台中的应用 ID 匹配 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: Tells Capgo where to find your root package.json : 告诉 __CAPGO_KEEP_0__ 在哪里找到您的根目录 node_modules 如果您的应用使用非标准结构，如单元仓库或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文档或联系支持团队获取帮助。

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

使用原生日志进行调试

原生日志调试

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

Android日志

Android日志

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

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

或者，您可以使用命令并使用grep过滤日志 adb logcat __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 将在更新过程中记录键事件，例如： Capgo 当更新检查被启动时

The Capgo SDK will log key events during the update process, such as:

  • __CAPGO_KEEP_1__
  • __CAPGO_KEEP_0__
  • 当更新下载开始并完成时
  • 当更新安装被触发时
  • 在原生更新步骤中发生的任何错误

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

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

iOS日志

标题为“iOS日志”

要访问iOS日志，请：

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

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

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

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

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

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

Electron日志

Electron日志

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

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

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

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

当遇到一个棘手的实时更新问题时，捕获 Capgo debug 日志和原生日志是很好的想法，才能获得一个全面了解发生了什么的图像。两个日志一起会给你最好的机会，识别并解决问题。

更新未应用

标题：更新未应用

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

  • 确保在您的应用中调用了 __CAPGO_KEEP_0__，如快速启动所示。 CapacitorUpdater.notifyAppReady() 检查您的设备是否连接到互联网，并且 code debug 日志显示更新已下载。 尝试完全关闭并重新打开应用程序，因为更新仅在新启动时应用。
  • Check that your device is connected to the internet and the Capgo debug logs show the update was downloaded
  • __CAPGO_KEEP_0__
  • __CAPGO_KEEP_0__

查看详细的更新流程，请参阅 部署实时更新 指南。如果您仍然遇到问题，请使用 npx @capgo/cli@latest app debug 命令和本机日志来获取更多关于发生的事情的可见性。

常见更新失败代码

标题为“常见更新失败代码”

如果您的日志显示后端错误，如 disable_auto_update_to_major, semver_error或 cannot_update_via_private_channel，请使用专门的指南：

It explains what each common code means, why it happens, and how to fix it.

SDK Installation

SDK 安装

如果您在安装 Capgo SDK 时遇到问题，请确保：

  • 您的应用程序使用支持的 Capacitor 版本（4.0 或更高版本）
  • 您遵循的快速入门步骤顺序，包括安装 __CAPGO_KEEP_0__ 后同步您的应用程序 CI/CD 集成 SDK CI/CD 集成

对于 CI/CD pipeline 触发 __CAPGO_KEEP_0__ 上传的问题：

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

For issues with triggering Capgo uploads from your CI/CD pipeline:

  • Double check your Capgo authentication token is set up correctly
  • CI/CD 集成
  • 对于 CI/CD pipeline 触发 __CAPGO_KEEP_0__ 上传的问题：

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

继续故障排除

标题：继续故障排除

如果您正在使用 故障排除 context:支持/高级支持页面或底部支持部分。角色：部分或页面标题。见：页面 support-policy.astro。消息键 `support_policy_troubleshooting_title` (支持政策故障排除标题)。 @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的实现细节。