一、跨端APP的热更新需求

APP团队同时维护iOS、Android、HarmonyOS三个平台，是目前很多移动端产品的常态。三个平台的发版节奏各自独立：iOS需要走App Store审核，Android需要逐家应用市场提交，HarmonyOS生态还在成长。三端紧急修复任何一个问题，都要等三条流程全部走完，业务响应速度被发版周期卡死。

技术团队长期处于被动状态：业务部门提出一个新功能需求，开发完成后还要等待各平台审核上线，响应周期以周计，无法匹配快速迭代的业务节奏。

小程序容器改变了这个局面。APP嵌入FinClip SDK后，所有功能以小程序形式运行在APP内部，不再依赖系统应用市场发版。业务部门提出需求、技术团队完成开发、后台一键发布——这个流程可以缩短到分钟级，实现真正的敏捷运营。后台发布新版本，三端同时感知，不需要三套发布流程。

二、小程序容器的热更新原理

APP集成FinClip SDK后，小程序运行时作为独立层嵌入宿主APP。运行原理与微信小程序一致：双线程模型中，JS逻辑线程负责业务计算，UI渲染线程（WebView）负责页面绘制。JS崩溃不会传染到APP主进程，用户打开的是一个小程序页面，不是H5网页。

小程序包由小程序管理后台统一管理，发布新版后通过后台下发机制触达用户设备。SDK负责接收包体、校验版本、决定是否加载新版。

三、用户何时能拿到新版——热更新的完整时间链

核心问题：运营在后台上传了新版本，用户的APP内部经历了什么？

SDK处理流程：

打开小程序时，SDK会先判断本地是否有缓存的小程序。如果没有，则直接从远程服务器下载小程序，然后打开；如果有缓存，则先加载本地版本，再校验服务器端是否有新版本。

后台发布新版小程序包
  ↓
用户打开小程序 → SDK检测到本地有旧版缓存
  ↓
SDK同时启动新版本下载（用户当前仍运行旧版）
  ↓
新版本下载完成，等待触发加载
  ↓
用户退出小程序，再次进入 → 加载新版

SDK检查时机可配置。初始化参数中可设置 appletIntervalUpdateLimit，控制后台自动检查更新的小程序个数，取值范围0~50，默认为3。设置为0代表关闭自动检查。

后台可按百分比、按城市、按用户群配置灰度规则，新版先在小范围可见，验证无问题后全量推送。灰度过程中可随时暂停或回滚。

通过代码主动触发版本检查时，调用 startApplet 接口：

// 启动小程序——触发热更新检查

Future<Map> startApplet(RemoteAppletRequest request)

RemoteAppletRequest request = new RemoteAppletRequest(
  apiServer: 'https://api.finclip.com',
  appletId: appId
);
request.startParams = {
  'path':'/pages/index/index',
  'query':'key1=value2&key2=value2'
};
Mop.instance.startApplet(request);

RemoteAppletRequest 的 startParams 支持传入 path 和 query，实现指定页面和参数初始化。

四、离线包机制——让用户首次打开就有完整功能

热更新解决了迭代问题，但用户首次使用某个功能时仍然需要等待下载。离线包机制让这个等待时间也可以消除。

offlineMiniprogramZipPath 和 offlineFrameworkZipPath 两个参数允许在APP内预置包体路径。用户首次打开时，SDK直接读取本地包，无需等待下载。

// 注意：工程assets目录下的离线包，需要先拷贝或移动到app工程沙盒目录。
val assets = listOf(
    "framework-3.2.3.zip",
    "5f17f457297b540001e06ebb-1.0.44.zip"
)
assets.forEach {
    val res = copyFile(getAssets().open(it), "$filesDir/$it")
    toast("拷贝文件$it:$res")
}

FinAppClient.appletApiManager.startApplet(
    this,
    IFinAppletRequest.Companion.fromAppId("https://api.finclip.com","5f17f457297b540001e06ebb")
        .setOfflineParams("$filesDir/framework-3.2.3.zip", "$filesDir/5f17f457297b540001e06ebb-1.0.44.zip")
)

离线包 + 热更新的组合策略：将最新版本的小程序包预置到APP内，线上迭代通过热更新管理，APP本身不发版。离线包保证首次体验，热更新保证迭代效率。

五、技术边界

发版不等于绕过所有审核：iOS App Store对含有动态代码执行能力的APP有审核政策要求，热更新能力在小程序层面不受限，但APP本身的容器逻辑仍需符合各平台商店规范。

包体大小需要评估：离线包预置会增加APP安装包体积，运营团队需要关注小程序包的体积增长趋势，避免单个包过大导致用户安装失败或更新耗时长。

热更新不等于实时推送：新版下载完成后需要用户重新进入才生效，不是推送通知式的强制更新，用户仍在控制是否要进入新版本。

六、常见问题复盘

6.1 首次打开时用户看到加载页

现象：后台发布新版后，用户首次打开小程序时页面一直显示加载状态，体验不佳。

原因：SDK检测到本地缓存旧版，开始后台下载新版，下载未完成前无法渲染页面，导致加载页停留时间超出预期。

解决：预置离线包到APP内，保证最新版本包在用户设备上已有缓存，热更新只负责增量更新而非全量下载。

6.2 灰度期间用户看到不同版本，数据状态不一致

现象：灰度发布10%用户期间，运营发现同一个功能的用户反馈数据出现了矛盾，有人说功能正常，有人说找不到入口。

原因：灰度范围内外用户运行不同版本，若功能涉及服务端接口变更，旧版调用的API与新版不一致，可能出现数据层面的不一致。

解决：灰度发布前确认服务端接口向后兼容，或者明确灰度范围只针对无数据依赖的功能模块。

6.3 离线包版本与后台最新版本不同步

现象：预置了离线包的用户打开小程序，跑的仍是旧版，后台已经全量发布的最新版没有生效。

原因：离线包优先于网络请求加载，APP内置的包版本与后台最新版本出现时间差。

解决：明确离线包的使用场景边界——适合低频功能或首次启动引导流程；高频核心功能不依赖离线包，直接通过热更新迭代。