故障排除

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

🚀 需要专家帮助?

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

获取专业支持

上传失败

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

• 您的应用 ID 是否与 __CAPGO_KEEP_0__ 控制台中的应用 ID 匹配 capacitor.config.ts 您是否从 Capgo 项目根目录运行上传命令
• 您是否从 Capacitor 项目根目录运行上传命令
• 您的 Web 资产已构建并且是最新的

高级上传选项

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

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

  npx @capgo/cli@latest bundle upload --tus

• --package-json 和 --node-modules: 告诉 Capgo 其根目录的位置 package.json and node_modules 如果您的应用程序使用非标准结构，如 monorepo 或 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 日志：

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 日志：

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

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

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

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

__CAPGO_KEEP_0__

• 下载更新时可能遇到的 iOS 特定问题包括：
• 下载更新时出现 SSL 证书问题
• 应用程序传输安全阻止更新下载
• 更新包装没有足够的存储空间

无法正确提取或应用更新包装

标题为“Electron 日志”

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

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

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

当遇到一个棘手的实时更新问题时，捕获 Capgo debug 日志和原生日志是有用的。两者一起会给你提供一个全面了解问题的视图，提高了找出和解决问题的机会。

更新未应用

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

• 确保您已在应用中调用 __CAPGO_KEEP_0__，如 quickstart 中所示。 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__

查看 live updates 更新指南 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的含义、原因和解决方法。

如果您遇到安装 Capgo SDK 的困难，请确保：

• 您的应用程序正在使用 Capacitor 的支持版本（4.0 或更高版本）
• 您已按照顺序遵循 "快速入门" 步骤，包括安装 __CAPGO_KEEP_0__ 后同步您的应用程序 CI/CD 集成 steps in order, including syncing your app after installing the SDK

对于 CI/CD pipeline 中触发 __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触发的更新是否被应用程序接收。