HarmonyOS ArkWeb 预取优化：预连接、prefetchPage与节流边界

HarmonyOS ArkWeb 预取优化：预连接、prefetchPage与节流边界

网页首屏慢，不一定是服务器慢。用户点击链接后，域名解析、TCP/TLS建连、HTML请求和子资源拉取才依次开始，任何一段都可能把等待放大。ArkWeb提供的预连接与页面预取，真正价值是把确定性较高的准备工作提前到“用户尚未点击”的空档，而不是无差别提前下载。

本文以商品列表进入详情页为例，给出一条可以落地的预取链路：启动阶段只预连接稳定域名，Web组件完成绑定后再预取高概率目标页，业务层负责去重与节流，真实跳转仍走正常加载。示例按API 21能力编写；较低API版本需要保留预连接方案并关闭prefetchPage分支。

1. 先确认等待发生在哪一段

不要看到白屏就直接增加预取。先在相同网络、相同账号和相同页面数据下记录四个时间点：用户点击、主文档请求发出、首字节返回、首屏可交互。若点击到请求发出的间隔很大，应优先检查主线程和路由；若建连耗时明显，预连接更有价值；若主文档与静态资源拉取占比高，才考虑prefetchPage。

点击到请求发出慢 -> 排查页面逻辑、线程阻塞和路由
DNS/TCP/TLS慢 -> prepareForPageLoad预解析或预连接
文档和子资源慢 -> prefetchPage预取高概率页面
渲染执行慢 -> 优化前端脚本、DOM和首屏资源

这个判断避免把网络优化手段用在渲染问题上。预取命中率低时，不但不会缩短体验，还会消耗流量、连接和服务端容量。

2. 三个动作承担不同职责

initializeWebEngine负责提前初始化Web引擎；静态方法prepareForPageLoad负责域名预解析或预连接；实例方法prefetchPage负责拉取目标页面需要的资源，但不执行JavaScript，也不渲染页面。

API 21的PrefetchOptions允许设置两次预取之间的最小间隔，并决定是否忽略Cache-Control: no-store。后者默认是false，生产项目通常应保持默认。

3. 预取闭环应该长什么样

闭环不是“拿到URL就下载”，而是识别候选、确认Web控制器可用、过滤敏感页面、执行节流、最后由真实导航消费缓存。候选URL必须来自用户已经表现出的意图，例如卡片进入可视区、搜索结果高亮或用户手指按下，而不是一次预取整个列表。

4. 在Ability阶段只做引擎和连接准备

下例把初始化放在UIAbility.onCreate。连接数并非越多越好，移动端通常从1或2开始验证；域名不稳定、会频繁切换CDN时，不应在启动阶段大量预连。

import { UIAbility } from '@kit.AbilityKit';
import { webview } from '@kit.ArkWeb';

export default class EntryAbility extends UIAbility {
onCreate(): void {
webview.WebviewController.initializeWebEngine();

try {
webview.WebviewController.prepareForPageLoad(
'https://shop.example.com',
true,
2
);
} catch (error) {
console.error(`prepare web connection failed: ${JSON.stringify(error)}`);
}
}
}

prepareForPageLoad接收完整URL、是否预连接以及预建socket数量。URL不合法或socket数量越界会抛出业务异常，因此不能把未经校验的用户输入直接传入。

5. 等控制器关联后再调用prefetchPage

prefetchPage是控制器实例方法。控制器尚未与Web组件关联时调用，会遇到初始化类错误。最稳妥的入口是onControllerAttached，页面预测服务也要在这个时间点之后才能执行。

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct ProductWebPage {
private controller: webview.WebviewController = new webview.WebviewController();
private attached: boolean = false;

build() {
Web({
src: 'https://shop.example.com/list',
controller: this.controller
})
.javaScriptAccess(true)
.onControllerAttached(() => {
this.attached = true;
})
}
}

不要用固定延时猜测绑定完成。设备性能、页面创建路径和窗口状态不同，固定500毫秒在一台设备上可用，在另一台设备上仍可能过早。

6. 把候选去重留给业务层

ArkWeb自身有频率限制，但业务层仍要处理相同URL重复进入可视区、快速滑动和多入口预测。下面的服务同时限制相同URL的重复预取和全局调用间隔。

import { webview } from '@kit.ArkWeb';

class PagePrefetcher {
private readonly recent: Map<string, number> = new Map();
private readonly duplicateWindowMs: number = 30_000;
private readonly globalIntervalMs: number = 1_200;
private lastCallAt: number = 0;

constructor(private controller: webview.WebviewController) {}

prefetch(rawUrl: string): boolean {
const now = Date.now();
const url = this.normalize(rawUrl);
if (!url || now – this.lastCallAt < this.globalIntervalMs) {
return false;
}
if (now – (this.recent.get(url) ?? 0) < this.duplicateWindowMs) {
return false;
}

const options = new webview.PrefetchOptions();
options.minTimeBetweenPrefetchesMs = this.globalIntervalMs;
options.ignoreCacheControlNoStore = false;
this.controller.prefetchPage(url, [], options);

this.lastCallAt = now;
this.recent.set(url, now);
return true;
}

private normalize(rawUrl: string): string {
const trimmed = rawUrl.trim();
return trimmed.startsWith('https://shop.example.com/') ? trimmed : '';
}
}

这里使用白名单域名而非简单判断https。如果详情URL带有一次性签名、短期令牌或用户隐私参数，应先生成不含敏感信息的可缓存地址，不能把完整私密URL写入日志或预取队列。

7. 预测信号要比点击早，但不能太早

推荐把信号按可靠程度分层：按下卡片通常最可靠，但提前量最短；卡片稳定进入屏幕中心有更长提前量；仅仅出现在列表尾部则误判更多。可以给每种信号设置信心阈值，只允许最高分候选进入预取器。

interface PageCandidate {
url: string;
score: number;
reason: 'press' | 'center-visible' | 'recommendation';
}

function chooseCandidate(items: PageCandidate[]): PageCandidate | undefined {
return items
.filter((item: PageCandidate) => item.score >= 0.75)
.sort((a: PageCandidate, b: PageCandidate) => b.score – a.score)[0];
}

只有候选变化且分数足够高时才触发。轮播图自动切换、广告曝光和后台刷新不应被当作用户导航意图。

8. 缓存头决定资源能否被复用

业务预测只负责“可能去哪里”，ArkWeb控制器负责“如何预取”，HTTP缓存负责“能否复用”，目标页面负责“真实加载”。四个边界不能混在一起。服务端返回Cache-Control: no-store时，默认不缓存是正确行为。

const options = new webview.PrefetchOptions();
options.minTimeBetweenPrefetchesMs = 1500;
options.ignoreCacheControlNoStore = false; // 保留HTTP安全语义

const headers: webview.WebHeader[] = [
{ headerKey: 'X-Client-Scene', headerValue: 'product-list' }
];
controller.prefetchPage(targetUrl, headers, options);

附加请求头必须与真实导航保持兼容。不要为预取单独拼接会改变响应内容的身份头，否则缓存对象与真实请求不一致，命中后也可能被重新验证。

9. 页面退出时清理业务侧状态

预取不是长期任务。页面销毁、账号切换或环境切换后，旧候选都应失效，尤其不能让测试环境URL残留到正式会话。

class PrefetchSession {
private active: boolean = true;

close(): void {
this.active = false;
}

canUse(url: string): boolean {
return this.active && url.startsWith('https://shop.example.com/');
}
}

ArkWeb缓存由引擎管理，业务层重点清理的是候选、计时器、账号相关URL和事件监听，不要在每次退出时盲目清空整个网页缓存。

10. 四类常见失败应分别处理

异常日志至少包含场景、归一化后的host、触发原因和错误码，不记录完整查询参数。这样既能定位调用时机，也不会泄露用户信息。

11. 用对照实验验收而不是凭感觉

固定设备、网络和页面数据，分别运行无优化、仅预连接、预连接加页面预取三组。每组至少重复20次，剔除首次安装、服务端发布和网络切换样本，再比较中位数与高分位耗时。

[ ] 预取候选命中率可以统计
[ ] 同一URL不会在短时间内重复触发
[ ] no-store资源仍遵循服务端缓存要求
[ ] 账号切换后旧URL不会继续使用
[ ] 弱网下未出现连接数和流量异常
[ ] 真实点击到首屏可交互耗时有稳定改善

12. ArkWeb预取资料索引

• ArkWeb组件能力概览
• WebviewController.prefetchPage、prepareForPageLoad与PrefetchOptions：以本机HarmonyOS SDK API 23类型声明为准。

预取的关键不是“更早请求”，而是“只提前做大概率会被消费的工作”。先定位瓶颈，再划分预连接、预取和缓存三层责任，最后用命中率与真实导航耗时决定是否保留，才能获得可持续的收益。