跳转到正文

故障排除

在使用 Capgo 时,你可能会遇到一些常见问题,以下是它们的解决方法。

🚀 需要专家帮助?

被复杂问题卡住了?我们的专家团队随时提供帮助!获取个性化支持、code 审查,以及针对你具体需求量身定制的解决方案。

如果 bundle 上传失败,请仔细检查:

  • 您的应用 ID 位于 capacitor.config.ts 与 Capgo 仪表板中的应用匹配
  • 您正在 Capacitor 项目根目录中运行上传命令
  • 您的 Web 资源已构建且为最新状态

Capgo CLI 提供了一些额外的标志,以帮助您解决常见的上传问题:

  • --tus:使用 tus 可断点续传上传协议 以便在上传大型 bundle 或网络连接较差时更可靠。如果您的 bundle 超过 10MB 或网络不稳定,可以考虑使用 --tus:

    终端窗口
    npx @capgo/cli@latest bundle upload --tus
  • --package-json 以及 --node-modules: 告知 Capgo 根目录的位置 package.json 以及 node_modules 如果您的应用使用了非标准结构(例如 monorepo 或 npm workspace),请将根目录路径传给 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 支持 以获得进一步帮助。

如果您在使用 Live Updates 时遇到问题,Capgo debug 命令是排查故障的好帮手。使用方法如下:

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

    终端窗口
    npx @capgo/cli@latest app debug
  2. 在真机或模拟器上启动应用,并执行触发更新的操作(例如:上传新 bundle 后重新打开应用)。

  3. 观察 debug 命令的输出。它会记录有关更新过程的信息,包括:

    • 应用检查更新的时间
    • 是否发现更新以及对应的版本号
    • 更新的下载和安装进度
    • 更新过程中发生的任何错误
  4. 利用 debug logs 定位问题所在。例如:

    • 如果未发现更新,请再次确认 bundle 已成功上传,且应用已配置为使用正确的 channel。
    • 如果更新已下载但未安装,请确保已调用 CapacitorUpdater.notifyAppReady() 并且应用已完全关闭并重新打开。
    • 如果看到错误消息,请在 Capgo 文档中查找这个具体错误,或联系支持团队获取帮助。

debug 命令对于识别更新下载和安装过程中的问题特别有用。如果日志显示找到了预期的更新版本但最终没有应用,请将排查重点放在下载之后的步骤上。

除了 Capgo debug 命令外,Android、iOS 和 Electron 上的原生日志也能提供有价值的排查信息,特别是针对更新过程中原生端的问题。

要访问 Android 日志:

  1. 连接您的设备或启动模拟器
  2. 打开 Android Studio 并选择“View > Tool Windows > Logcat”
  3. 在 Logcat 窗口中,从顶部下拉菜单中选择您的应用进程,只显示该进程的日志。
  4. 查找包含以下内容的任意行: Capgo 以找到 SDK 日志。

或者,您也可以使用 adb logcat 命令,并用 grep 查找 Capgo 来过滤日志。

Capgo SDK 会在更新过程中记录关键事件,例如:

  • 当发起更新检查时
  • 是否发现更新以及对应的版本号
  • 当更新下载开始和完成时
  • 当触发更新安装时
  • 原生更新步骤中发生的任何错误

日志中可能出现的常见 Android 特定问题包括:

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

要访问 iOS 日志:

  1. 连接您的设备或启动模拟器
  2. 打开 Xcode,前往“窗口 > 设备和模拟器”
  3. 选择您的设备,点击“打开控制台”
  4. 在控制台输出中,查找包含以下内容的行 Capgo 以找到 SDK 日志。

你也可以使用 log stream 在终端中运行命令,并 grep 以下内容 Capgo 来过滤日志。

与 Android 类似,Capgo SDK 会记录关键的 iOS 端事件:

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

您可能在日志中识别出的 iOS 特定问题包括:

  • 下载更新时的 SSL 证书问题
  • App Transport Security 阻止更新下载
  • 更新 bundle 存储空间不足
  • 无法正确解压或应用更新 bundle

对于 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 层之外的问题特别有用。

排查棘手的 live update 问题时,建议同时捕获 Capgo 调试日志和原生日志,以全面了解情况。结合这两类日志,能最大程度地帮助你定位并解决问题。

如果已上传 bundle,但设备上没看到变化:

  • 请确保已调用 CapacitorUpdater.notifyAppReady() 在应用的 code 中,如下所示 快速入门
  • 检查设备是否已联网,并确认 Capgo 调试日志显示更新已下载
  • 尝试彻底关闭并重新打开应用,因为更新只会在全新启动时生效
  • 查看原生日志中是否有错误,这些错误可能表明应用更新时出了问题

请参阅 部署 Live Updates 指南,了解更新流程的更多细节。如果仍然卡住,请使用 npx @capgo/cli@latest app debug 命令和原生日志,以更深入地了解正在发生的情况。

如果日志显示后端错误,例如 disable_auto_update_to_major, semver_error,或 cannot_update_via_private_channel,请使用专用指南:

它解释了每个常见 code 的含义、发生原因以及修复方法。

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

  • 您的应用使用的是受支持的 Capacitor 版本(4.0 或更高版本)
  • 您已按照 快速入门 步骤依次操作,包括在安装 SDK 后同步您的应用

关于从 CI/CD 流水线触发 Capgo 上传的问题:

  • 请仔细检查您的 Capgo 身份验证令牌是否已正确配置
  • 请确保在 Web 资源构建完成后再运行 upload 命令
  • 请检查 upload 命令是否使用了目标环境的正确 channel 名称

请参阅 CI/CD 集成 docs 以获取更多故障排除技巧。您还可以使用 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. 的实现细节