如何排查离线包(H5应用或小程序)无法更新的问题

问题定义

当一个 H5 应用或小程序需要更新时,开发者通过 mPaaS 离线包发布平台上传这个 H5 应用的更新包或小程序的更新包,并赋予一个新的版本号。在客户端,App 会主动询问服务端某个 H5 应用或小程序的离线包是否存在版本更新,如果有,服务端会告知客户端更新包的详细信息,客户端则根据信息按需主动下载新的资源包到本地并解压覆盖之前的离线资源文件,从而实现离线资源的更新。如果离线包无法更新,对用户体验有较大影响。

常见症状

开发者通过 MDS(实时发布服务)发布了一个新的 H5 应用离线包或一个新的小程序包,而客户端打开 H5 应用或小程序时,依然是旧版内容,不符合预期。

排查手段

在离线包更新的问题上,如果开发者对排查方向不是非常明确,建议参考 通过 HTTP 包排查分析 抓取 HTTP 包,根据 HTTP 包中的行为来分析排查更新问题。

MDS 发布配置检查

  1. 首先需要确认目标离线包的版本在 发布 状态中。发布如果不在 发布 状态中,请单击 创建发布 创建一个特定版本的发布任务。

  2. 检查 发布任务 覆盖的客户端版本范围。对目标离线包版本点击 查看,查看详细信息:查看检查覆盖的客户端版本范围:检查

    客户端版本范围 中的版本号指基于 mPaaS 框架的 iOS 或 Android 原生应用的版本号。特别的,iOS 客户端的版本号值并不是 Xcode 项目的版本号,而是 info.plistProduction Version 字段的值。Android 客户端的版本号值是 build.gradleversionName 字段的值。

  3. 建议对于一个离线包或小程序包,尽量保持足够精简的发布任务,例如一个到两个。对于陈旧的离线包版本发布任务,如果不再使用,请停止或删除发布任务,避免 MDS 缓存出现异常。

客户端配置检查

  1. 确认更新代码逻辑。mPaaS iOS 或 Android 客户端开发框架都提供了离线包主动更新的 API 接口。正常情况下,每次打开离线包,框架自身也会主动检查是否存在更新。请确认 mPaaS 框架和 H5 容器或离线包组件接入是否正确,API 使用是否正确。如果调用了主动更新 API,请确认调用时机,排查 requestAllNebulaApp(iOS)/updataAll(Android) 是否被正确调用。

  2. 确认客户端版本号是否在离线包或小程序包的发布范围内。

    • iOS,检查 info.plistProduction Version 字段值是否在离线包或小程序包的发布范围内。

    • Android,检查 build.gradleversionName 字段值是否在离线包或小程序包的发布范围内。

  3. 检查获取更新的 RPC 请求返回是否正常。在控制台中查看调用 update API 时发出的 RPC 请求是否正确返回。

通过HTTP包排查分析

更新单个离线包的过程

正常情况下,单个离线包的正常更新过程如下:

  1. 客户端向 MDS 服务端发送请求,请求中提供了需要更新的目标 H5 App 的 ID 和本地版本号。

  2. 服务端返回该离线包的相关更新信息(如果存在)。

  3. 客户端根据返回信息中的 增量包地址 并结合返回信息中的 下载配置参数,主动去下载更新包的 amr 文件(如果没有增量包地址,则根据 Package URL 下载全量包)。

操作步骤
  1. 请求离线包信息。请求离线包信息

  2. 返回离线包更新信息。返回离线包更新信息

  3. 客户端根据上一步拿到的增量包的 URL 去下载对应的 amr 文件。下载arm文件

说明

抓取到的离线包示例:2-offline-package-update-example.chls.zip

更新所有离线包的过程

iOS 和 Android 平台均提供了 API 实现一次请求所有离线包的更新信息,其基本过程如下:

  1. 客户端向 MDS 服务端发送请求,请求中提供了本地已安装的所有 H5 App 的 ID 和本地版本号,外加一个特殊的 App ID: nebula-*-all

  2. 服务端返回所有符合条件的离线包信息(不在客户端版本范围内的,不返回)。

  3. 客户端根据返回信息中的内容,主动去下载全量或增量的 amr 文件。

操作步骤
  1. 请求离线包信息。请求离线包信息

  2. 返回所有符合要求的离线包信息。返回离线包信息

  3. 客户端根据上一步拿到的 URL 去下载所有的 amr 文件。下载arm文件

说明

抓取到的离线包示例:2-offline-package-update-example.chls.zip

HTTP 包排查要点

  1. 查看 离线包更新信息 请求体中的客户端版本号,确认是否在离线包发布客户端版本范围内。请求版本号

  2. 查看 离线包更新信息 请求体中是否带有 目标离线包的 App ID 或带有 nebula-*-all 字段。查看是否有某个字段

  3. 确认离线包更新信息 请求的返回数据中是否包含目标离线包及相关信息(amr 地址,fallback 地址等)。查看相关信息

  4. 确认 amr 文件下载过程是否正常。确认下载过程

阿里云首页 移动开发平台 mPaaS 相关技术圈