排查指南 | 两个案例学会从埋点排查 iOS 离线包

离线包原理

以一次启动离线包的流程为例，离线包的加载流程分为两种场景，第一种是离线包下载好的场景，流程如图1所示，第二种是离线包没下载好的场景，如图2所示：

图1：离线包加载主流

图2：离线包下载流程

我们可以从埋点来跟踪离线包具体的加载流程*：

1. 检查本地是否有离线包，本地有则执行第四步解压，解压之后再进行校验，校验通过加载本地离线包，如果本地已经安装过，那就不需要解压直接走解压后的流程
2. 网络请求离线包信息，这一步和上一步是异步进行的，对应的埋点有 H5_APP_REQUEST
3. 对比请求回来的离线包信息，再决定是否下载离线包，对应的埋点有 H5_APP_DOWNLOAD
4. 解压离线包，对应的埋点有 H5_APP_UNZIP
5. 如果开启了离线包验签，校验离线包的合法性，对应的埋点有 H5_APP_VERIFY、H5_AL_SESSION_VERIFYTAR_FAIL
6. 加载本地离线包，对应的埋点有 H5_AL_SESSION_MAP_SUCCESS、H5_AL_SESSION_FALLBACK

注意：fallback走线上需要等到离线包请求这个异步请求回调回来之后返回的 fallback + mainUrl 确定 Webview 打开的URL。

*参考资料：离线包日志埋点

案例1：首次打开离线包白屏

STEP1：按照离线包加载流程分析，首次打开离线包一定是需要走线上的fallback，因为本地没有，走线上之前一定需要先知道离线包的线上地址也就是URL，所以需要查看日志分析是否是请求离线包信息那一步出错了。

STEP2：分析日志打开线上离线包的时候URL为空，在离线包请求还没有回调回来之前就打开离线包，所以出现了白屏。

STEP3：检查代码

将创建的离线包控制器作为根视图，时机过早，所以导致了该问题。

STEP4：结合客户需求给出建议，可以使用本地预制离线包解决首次过早打开离线包出现白屏的问题。

案例2：打开预置离线包，报错（-1009）

复现demo

STEP1：断网情况下打开预制离线包失败显示网络无法连接说明打开预制包失败了，所以走了线上，由于没有网络所以显示网络无法连接，问题出在本地预制的离线包上。

STEP2：按照离线包的加载流程分析，在本地有预制包的情况下出现走线上的情况分别有两种情况，离线包验证签名失败和加载本地离线包失败。

STEP3：日志分析

观察到有验签失败的字样。

STEP4：检查代码客户端是否关闭了验签，默认是开启的，如果没有关闭，那么客户端需要设置对应的公钥，或者关闭验签。

STEP5：关闭验签再试一遍，继续分析日志：

H5_AL_SESSION_FALLBACK加载本地离线包失败，最终走的线上，观察解压离线包成功没有问题，问题出在加载离线包那一步，日志中查找到H5_APP_EXCEP离线包异常埋点，是读取数据时候失败了。

STEP6：问题有可能出现在该离线包上面，所提供一个正常的离线包给客户做成本地预制离线包，断网打开验证，没有问题，问题就出在该离线包上。

STEP7：解开预制的离线包，观察离线包是否路径字符总长度是否超过了限制导致读取数据失败。

JS文件名称过长，导致总的字符长度超过了限制，需要客户修改离线包*。

*参考资料：生成离线包

思考和总结

通过上面两个案例的介绍，我们可以清晰的看到案例一最终出现问题的原因是请求离线包信息这个请求没有回调回来，客户就打开离线包时没有获取到URL，问题出现在了请求离线包那一步了，而案例二最终定位到加载本地包失败那一步。

了解了离线包的具体加载流程，再结合 nebula 容器自动化埋点日志，就可以具体定位问题到离线包加载的哪一步了。

本文作者：阿里云 mPaaS TMA 团队（杨强 荣阳）

END

---

下周二（8.24）阿里云飞天会员日开启，消息推送等资源包1折秒杀抢购，点击了解更多折扣详情。