HarmonyOS 7 ArkWeb M144 离线包更新：资源只下载了一半，怎样避免切换到坏缓存

离线网页更新时，如果下载一个资源就立即写进当前缓存，新入口可能引用新脚本和旧样式，甚至缺失必要文件。更新应先在独立暂存区完成，再一次性切换有效版本指针。失败只丢弃暂存区，不能破坏正在使用的版本。

版本与适用范围

官方 ArkWeb 简介列出 HarmonyOS 7.0 默认推荐 M144，同时有可选 M132 及对应适配指导。下面验证应用侧离线包提交逻辑，不声称这是内核默认缓存机制，也不把迁移后所有白屏归因于缓存。

官方参考文档，核对日期：2026-09-14。下面的 JavaScript 实验可以直接用 Node.js 运行；它验证应用侧算法与状态边界，不是已经在 HarmonyOS SDK 或真机上跑通的完整应用。应用接入时，SDK 调用、事件订阅和资源释放应分别验证。

问题是怎样发生的

入口下载成功、app 下载失败，active 应完整保持 v1，不出现新旧文件混合。

复现不依赖随机等待。测试用固定输入、显式完成的异步结果或明确的状态变化，让错误条件可以重复出现。先保留失败信号，再检查修复后的状态，避免只看“没有抛异常”就认为问题解决。

案例一：脚本下载中途失败

入口下载成功、app 下载失败，active 应完整保持 v1，不出现新旧文件混合。

案例二：全部下载成功与入口缺失

v2 两个资源齐全时才切换；后续只有 app 没有 index 的清单必须拒绝，v2 保持可用。

实现代码

export class OfflinePackages {
  active = {version:'v1', files:new Map([['index','old']])};
  async update(version, manifest, fetchFile) {
    if (!version || !manifest.length || new Set(manifest).size !== manifest.length) throw Error('invalid_manifest');
    const staging = new Map();
    for (const path of manifest) {
      const data = await fetchFile(path);
      if (typeof data !== 'string' || !data.length) throw Error('empty_resource:' + path);
      staging.set(path, data);
    }
    if (!staging.has('index')) throw Error('missing_entry');
    this.active = {version, files:staging};
    return version;
  }
}

运行验证

把上面的实现和下面的测试按顺序放进同一个 example.mjs 文件，使用 Node.js 执行 node example.mjs。测试采用 Node 内置的 assert，不需要第三方依赖。断言失败时进程报错，全部通过时正常退出。

import assert from 'node:assert/strict';
const packages = new OfflinePackages();
await assert.rejects(packages.update('v2', ['index','app'], async p => {
  if (p === 'app') throw Error('offline'); return 'new';
}));
assert.equal(packages.active.version, 'v1');
assert.equal(packages.active.files.get('index'), 'old');
assert.equal(await packages.update('v2', ['index','app'], async p => 'new:' + p), 'v2');
assert.equal(packages.active.files.size, 2);
await assert.rejects(packages.update('v3', ['app'], async () => 'data'));
assert.equal(packages.active.version, 'v2');

核对时不要把输入样本当作性能数据。上述测试已经在 Node.js 环境逐项执行通过，验证的是代码中写出的条件。涉及窗口、材质、音频或系统入口的真实表现，需要另外在适配设备验证。

为什么选择这个方案

逐文件覆盖节省暂存空间，但没有一致性边界；独立版本目录加原子指针更容易回滚。内存对象赋值在这个实验中代表提交点，落到文件系统时要验证目录重命名或指针文件更新的原子性。

检查项	实验中的做法	接入应用时要补的验证
输入边界	拒绝非法输入或区分失效请求	SDK 返回类型与错误码
状态变化	显式记录每次操作的输入和结果	页面切换、窗口销毁与后台恢复
失败路径	断言旧状态不被错误结果覆盖	弱网、权限拒绝与设备能力缺失
成功路径	检查最终状态，而非只检查无异常	目标设备界面与真实资源行为

逐文件覆盖为何会制造半更新状态

错误方案的提交点分散在每个文件下载之后。入口成功后立即替换，脚本失败却保留旧脚本，最后形成新入口配旧脚本。下面运行这个错误版本并检查具体文件内容，再对暂存方案做相同输入。断言同时检查版本指针与文件内容，避免版本字符串没变就误认为旧包完整。

继续在同一个 example.mjs 文件中追加以下代码，使用已经定义的实现和 assert 再运行一次。

export async function badOverwrite(files, manifest, fetchFile) {
  for (const path of manifest) files.set(path, await fetchFile(path));
}
const oldFiles = new Map([['index','old-index'],['app','old-app']]);
const interruptedFetch = async path => {if (path === 'app') throw Error('offline'); return 'new-index';};
await assert.rejects(badOverwrite(oldFiles, ['index','app'], interruptedFetch));
assert.equal(oldFiles.get('index'), 'new-index');
assert.equal(oldFiles.get('app'), 'old-app');
const atomicPackages = new OfflinePackages();
atomicPackages.active = {version:'v1',files:new Map([['index','old-index'],['app','old-app']])};
await assert.rejects(atomicPackages.update('v2',['index','app'],interruptedFetch));
assert.equal(atomicPackages.active.version, 'v1');
assert.equal(atomicPackages.active.files.get('index'), 'old-index');
assert.equal(atomicPackages.active.files.get('app'), 'old-app');

接入应用时的取舍

正式包下载到独立版本目录，校验每个文件的摘要、大小与路径，再更新当前版本指针。已打开的 Web 页面可以继续使用旧版本，新会话再取得新指针，避免加载过程中资源版本突变。保留上一版直到新版本自检通过，然后按空间策略清理。更新失败日志应记录失败资源与目标版本，不要记录带授权信息的 URL。内核升级的兼容排查还要检查 Console 错误、网络响应和权限结果，离线包一致性只是其中一项。

封装与复用

把上面的纯逻辑保留为独立模块，界面层只提交输入和消费结果。系统事件适配层负责取得当前窗口、设备或入口的实际数据，不要把测试常量直接搬到正式应用。这样单元测试仍可在没有设备时运行，SDK 接入问题也能和算法问题分开排查。

复用之前先检查实例的作用域：窗口、播放器或请求协调器是否属于同一个会话。复用函数不等于共享所有状态。对于异步回调，需要同时考虑结果失效与底层任务取消；对于同步计算，需要确认单位、取样范围和输入上限。

边界与后续检查

实际包还需做大小限制、来源校验、内容摘要验证与路径穿越检查。示例没有把非空字符串等同于可信脚本；它只验证完整性提交，不验证文件真实性。并发更新还需要串行化或比较版本的规则。

回归测试应保留两个案例，再增加空输入、重复入口和生命周期结束后的操作。日志记录输入身份、状态修订与失败原因，不记录敏感内容。升级 SDK 后先检查官方接口签名、支持设备与版本说明，再运行同一组实验和设备回归，避免把旧版本假设带入新环境。