故障排除

可复制

Here are some common issues you might encounter while using Capgo and how to resolve them.

🚀 需要专家帮助?

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

获取专业支持

上传失败

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

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

高级上传选项

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

--tus: 使用 tus 可恢复上传协议更可靠地上传大型捆绑包或在网络连接不稳定的情况下。如果您的捆绑包超过 10MB 或您在一个不稳定的网络连接上，请考虑使用 --tus:
终端窗口
```
npx @capgo/cli@latest bundle upload --tus
```
--package-json 和 --node-modules：告诉 Capgo 在哪里找到您的根 package.json 和 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调试命令是一个有用的工具来帮助您排查问题。要使用它，请遵循以下步骤：

在您的项目目录中运行以下命令：
终端窗口
```
npx @capgo/cli@latest app debug
```
在设备或模拟器上启动您的应用，并执行应该触发更新的操作（例如重新打开应用程序后上传新包）。
查看调试命令的输出。它将记录有关更新过程的信息，包括：
- 应用程序检查更新时
- 如果找到更新并且是什么版本
- 下载和安装更新进度
- 任何在更新过程中出现的错误
使用调试日志来确定问题出在哪里。例如：
- 如果找不到更新，请检查一下你的包是否已经成功上传，并且应用程序配置了正确的渠道。
- 如果更新下载了但没有安装，请确保你已经调用了 CapacitorUpdater.notifyAppReady() 并且应用程序已经完全关闭并重新打开。
- 如果你看到一个错误信息，请查阅Capgo文档或联系支持团队来获取帮助。

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

使用原生日志进行调试

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

Android 日志

要访问Android日志，请访问：

连接您的设备或启动模拟器
打开Android Studio并选择“视图>工具窗口>Logcat”
在Logcat窗口中，仅显示您的应用程序进程的日志，请从顶部下拉菜单中选择它
查找包含 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:

如果发现更新并且是什么版本
__CAPGO_KEEP_1__
当更新下载开始并完成时
当更新安装被触发时
在原生更新步骤中发生的任何错误

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

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

iOS日志

要访问iOS日志:

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

您也可以使用 log stream 命令在终端中并使用grep来过滤日志 Capgo 类似于 Android，__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 将记录 iOS 端的关键事件:

Similar to Android, the Capgo SDK will log key iOS-side events:

下载开始、进度和完成
安装触发器和结果
原生更新过程中的任何错误
Update check initiation and result

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

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

Electron日志

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

使用您的正常启动命令从终端运行Electron应用（例如 bun run electron:dev 或 bun run electron:serve并在启动、更新检查和网络错误期间监视终端输出。
在渲染窗口中打开开发工具（视图→切换开发工具）并在重现更新流程时检查控制台日志和失败的网络请求。
对于打包应用程序，请检查操作系统日志工具以查找崩溃或启动失败：
- 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
Section titled “
Look for any errors in the native logs that might indicate a problem applying the update

查看以下部署实时更新指南获取更多关于更新过程的详细信息。如果您仍然卡住，请使用 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

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

您的应用程序使用支持的 Capacitor 版本（4.0 或更高版本）
您遵循了快速入门步骤，包括安装 SDK 后同步您的应用程序

CI/CD 集成

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

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

查看 CI/CD 集成更多的故障排除提示，请参阅 npx @capgo/cli@latest app debug 您可以使用

继续

如果您正在使用 故障排除 来规划存储和文件处理，连接它到 @capgo/capacitor-data-storage-sqlite for the implementation detail in @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的实现细节。