🚀 需要专家帮助?
被复杂问题卡住了?我们的专家团队随时提供帮助!获取个性化支持、code 审查,以及针对你具体需求量身定制的解决方案。
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
在使用 Capgo 时,你可能会遇到一些常见问题,以下是它们的解决方法。
🚀 需要专家帮助?
被复杂问题卡住了?我们的专家团队随时提供帮助!获取个性化支持、code 审查,以及针对你具体需求量身定制的解决方案。
如果 bundle 上传失败,请仔细检查:
capacitor.config.ts 与 Capgo 仪表板中的应用匹配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_modulesCapgo 需要这些信息才能正确打包应用的依赖项。
您可以将这些标志与其他选项(如 --channel )按需组合使用。请参阅 Capgo CLI 文档 了解可用上传选项的完整详情。
如果上传时仍遇到问题,请联系 Capgo 支持 以获得进一步帮助。
如果您在使用 Live Updates 时遇到问题,Capgo debug 命令是排查故障的好帮手。使用方法如下:
在项目目录中运行以下命令:
npx @capgo/cli@latest app debug在真机或模拟器上启动应用,并执行触发更新的操作(例如:上传新 bundle 后重新打开应用)。
观察 debug 命令的输出。它会记录有关更新过程的信息,包括:
利用 debug logs 定位问题所在。例如:
CapacitorUpdater.notifyAppReady() 并且应用已完全关闭并重新打开。debug 命令对于识别更新下载和安装过程中的问题特别有用。如果日志显示找到了预期的更新版本但最终没有应用,请将排查重点放在下载之后的步骤上。
除了 Capgo debug 命令外,Android、iOS 和 Electron 上的原生日志也能提供有价值的排查信息,特别是针对更新过程中原生端的问题。
要访问 Android 日志:
Capgo 以找到 SDK 日志。或者,您也可以使用 adb logcat 命令,并用 grep 查找 Capgo 来过滤日志。
Capgo SDK 会在更新过程中记录关键事件,例如:
日志中可能出现的常见 Android 特定问题包括:
要访问 iOS 日志:
Capgo 以找到 SDK 日志。你也可以使用 log stream 在终端中运行命令,并 grep 以下内容 Capgo 来过滤日志。
与 Android 类似,Capgo SDK 会记录关键的 iOS 端事件:
您可能在日志中识别出的 iOS 特定问题包括:
对于 Electron 应用,请同时检查主进程和渲染进程的输出:
bun run electron:dev 或 bun run electron:serve),并留意终端输出中的启动信息、更新检查和网络错误。Console.app 并按应用名称过滤journalctl 查看应用进程调试更新时,请对比主进程和渲染进程的日志消息,以区分 Electron 引导问题与 Capgo 更新生命周期问题。
跨平台来看,原生日志提供了更新过程的底层视图,包含更多原生实现细节。它们对于识别发生在 Capgo JavaScript 层之外的问题特别有用。
排查棘手的 live update 问题时,建议同时捕获 Capgo 调试日志和原生日志,以全面了解情况。结合这两类日志,能最大程度地帮助你定位并解决问题。
如果已上传 bundle,但设备上没看到变化:
CapacitorUpdater.notifyAppReady() 在应用的 code 中,如下所示 快速入门请参阅 部署 Live Updates 指南,了解更新流程的更多细节。如果仍然卡住,请使用 npx @capgo/cli@latest app debug 命令和原生日志,以更深入地了解正在发生的情况。
如果日志显示后端错误,例如 disable_auto_update_to_major, semver_error,或 cannot_update_via_private_channel,请使用专用指南:
它解释了每个常见 code 的含义、发生原因以及修复方法。
如果您在安装 Capgo SDK 时遇到问题,请确保:
关于从 CI/CD 流水线触发 Capgo 上传的问题:
请参阅 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. 的实现细节