跳转到正文
Capgo - 构建、发布并更新 Capacitor 应用 Capgo

故障排除

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

🚀 需要专家帮助？

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

上传失败

标题为“Upload failures”的部分

如果 bundle upload 失败，请检查：

  • Your app ID in capacitor.config.ts 是否与 Capgo dashboard 中的 App 一致
  • 你是否在 Capacitor 项目的根目录下运行 upload 命令
  • 你的 Web assets 已构建且为最新版本

高级 upload 选项

标题为“Advanced upload options”的部分

Capgo CLI 提供了一些额外的 flag，以帮助解决常见的 upload 问题：

  • --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 需要这些信息来正确打包应用的依赖项。

你可以根据需要将这些 flag 与其他选项结合使用，例如 --channel 如需了解详情，请参阅 Capgo CLI 文档 以获取可用 upload 选项的完整细节。

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

调试更新

标题为 “Debugging Updates” 的章节

如果你在 live updates 方面遇到问题，Capgo debug 命令是排查故障的得力工具。使用方法如下：

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

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

  2. 在真机或模拟器上启动应用，并执行触发更新的操作（例如：上传新 bundle 后重新打开应用）。

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

    • 应用检查更新的时间
    • 是否发现更新以及对应的版本号
    • 更新的下载和安装进度
    • 更新过程中发生的任何错误

  4. 利用 debug logs 定位问题所在。例如：

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

debug 命令对于排查更新下载和安装过程中的问题非常有用。如果日志显示已找到预期的更新版本但最终未应用，请重点排查下载之后的步骤。

使用 Native Logs 进行调试

标题为“使用 Native Logs 进行调试”的章节

除了 Capgo debug 命令外，Android、iOS 和 Electron 的 native logs 也能提供非常有价值的排查信息，特别是针对更新过程中原生层面的问题。

Android 日志

标题为“Android Logs”的章节

访问 Android logs 的步骤：

  1. 连接设备或启动模拟器
  2. 打开 Android Studio，选择 “View > Tool Windows > Logcat”
  3. 在 Logcat 窗口中，通过顶部的下拉菜单选择你的应用进程，以过滤日志
  4. 查找包含以下内容的行： Capgo 查找 SDK 日志

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

Capgo SDK 会记录更新过程中的关键事件，例如：

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

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

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

iOS 日志

标题为 “iOS Logs” 的章节

如何查看 iOS logs：

  1. 连接设备或启动模拟器
  2. 打开 Xcode，前往 “Window > Devices and Simulators”
  3. 选择您的设备并点击 “Open Console”
  4. 在控制台输出中，查找包含以下内容的行 Capgo 以找到 SDK logs

你也可以使用 log stream 在终端运行命令并使用 grep 查找 Capgo 以过滤日志。

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

  • 更新检查的启动与结果
  • 下载的开始、进度及完成情况
  • 安装触发与结果
  • Native Build 更新过程中的任何错误

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

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

Electron 日志

标题为“Electron 日志”的章节

对于 Electron 应用，请同时检查主进程和渲染进程的输出：

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

在调试更新时，请对比主进程 (main-process) 和渲染进程 (renderer-process) 的日志信息，以便将 Electron 启动问题与 Capgo 更新生命周期问题区分开来。

在不同平台上，原生日志 (native logs) 都能提供更底层的更新过程视图，包含更多关于原生实现的细节。对于排查发生在 Capgo JavaScript 层之外的问题，原生日志尤其有用。

在排查棘手的 live update 问题时，建议同时获取 Capgo 调试日志和原生日志，以便全面了解当前状况。结合这两份日志将极大提升您定位并解决问题的概率。

更新未生效

标题为“更新未生效”的部分

如果你已经上传了 bundle，但设备上没有看到变化：

  • 请确保你已在应用中调用了 CapacitorUpdater.notifyAppReady() 如 code 所示，请参考 快速入门
  • 检查设备是否已联网，并确认 Capgo 调试日志显示已下载更新
  • 尝试彻底关闭并重新启动应用，因为更新仅在应用冷启动时生效
  • 查看原生日志中是否存在可能导致更新应用失败的错误

请参阅 部署 Live Updates 指南以了解更多更新流程详情。如果问题仍然存在，请使用 npx @capgo/cli@latest app debug 命令并查看原生日志，以获取更详细的运行状态。

常见的更新失败错误码

“常见更新失败代码”章节

如果你的 logs 显示如下后端错误： disable_auto_update_to_major, semver_error，或 cannot_update_via_private_channel请参考专用指南：

该指南解释了每个常见的 code 的含义、发生原因以及解决方法。

SDK 安装

“SDK 安装”章节

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

  • 你的 App 使用的是受支持的 Capacitor 版本 (4.0 或更高版本)
  • 你已按照 快速入门 按顺序执行步骤，包括安装 SDK 后同步您的应用

CI/CD 集成

标题为 “CI/CD Integration” 的章节

如果无法从 CI/CD pipeline 触发 Capgo upload：

  • 请仔细检查您的 Capgo authentication token 是否配置正确
  • 确保在 web assets build 完成后运行 upload 命令
  • 检查 upload 命令是否为目标环境使用了正确的 channel 名称

请参阅 CI/CD 集成 查看 docs 获取更多排查技巧。您还可以使用 npx @capgo/cli@latest app debug command 来确认应用是否已接收到由 CI/CD 触发的 updates。

从 Troubleshooting 继续

标题为“从故障排除继续”的章节

如果你正在使用 故障排除 要规划存储和文件处理，请将其与 @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. 的实现细节