跳转到内容

Service Worker 中的 API

NavigationPreloadManager

发布于

NavigationPreloadManager 让浏览器在 service worker 启动期间就发出导航请求,省去等待 worker 启动后调用 fetch() 的时间。用 registration.navigationPreload 访问管理器,worker 从 FetchEvent.preloadResponse 读取提前请求的响应。它自 Chrome 59、Edge 79、Firefox 99、Safari 15.4 起可用(BCD api.NavigationPreloadManager),且仅限安全上下文。

// service worker 中(或页面中经由 navigator.serviceWorker.ready)
await registration.navigationPreload.enable();
await registration.navigationPreload.disable();
await registration.navigationPreload.setHeaderValue(value);
const state = await registration.navigationPreload.getState();
// service worker 的 fetch 处理函数内
const preloaded = await event.preloadResponse; // Response 或 undefined

预加载是按注册保存的设置,跨 worker 重启与更新持续有效,所以只需启用一次(通常在 activate 中),无需每次启动都重新启用。

管理器的四个方法都返回 Promise,状态对象有两个字段。

成员 返回值 行为
enable() Promise<void> 为该注册开启预加载。之后 scope 内的 GET 导航都会并行发出一个带 Service-Worker-Navigation-Preload 请求头的 GET。
disable() Promise<void> 关闭预加载。此后每次导航的 event.preloadResponse 都兑现为 undefined。
setHeaderValue(value) Promise<void> 设置预加载请求所带 Service-Worker-Navigation-Preload 头的值。默认为 true。
getState() Promise<{ enabled: boolean, headerValue: string }> 报告预加载是否开启及当前的头值。
FetchEvent.preloadResponse Promise<Response | undefined> 预加载开启时导航 GET 的预加载响应;子资源、非 GET 请求以及预加载关闭时为 undefined。

服务器可以根据这个标头为预加载请求返回不同内容,例如 worker 自己渲染应用壳时,只返回 JSON 数据,无需完整 HTML。按这个标头分流的服务器必须发送 Vary: Service-Worker-Navigation-Preload,否则中间的 HTTP 缓存可能把预加载变体交给普通导航。

四个方法报错时都拒绝 Promise,错误类型为 DOMException 或 TypeError,不会同步抛出。

  • InvalidStateError:注册上没有处于 active 状态的 worker。在 install 中(worker 仍在安装)调用 enable() 会被拒绝;activate 是最早的安全时机,页面侧对应的是 navigator.serviceWorker.ready。
  • setHeaderValue() 的 TypeError:value 不是合法的 HTTP 头值(必须是不含控制字符与换行的字节串)。
  • 不是异常:预加载响应未被使用。处理函数返回了缓存响应且从未 await event.preloadResponse 时,浏览器已经花掉了这次请求。只有需要消费它时才把 Promise 交给 event.waitUntil();否则要么接受这次浪费的请求,要么对总是从缓存应答的路由关闭预加载。
  • 不是异常:浏览器支持该管理器但本注册关闭了预加载时,event.preloadResponse 兑现为 undefined。假定它一定是 Response 的代码会在第一次访问属性时抛出 TypeError: Cannot read properties of undefined。

启用预加载后,要在 fetch 处理器中读取响应;还需检测支持情况,让处理器在没有预加载时也能工作。

等 worker 进入 active 后再启用,并把调用放在 waitUntil() 内,以免激活在设置写入之前就结束。

self.addEventListener('activate', (event) => {
event.waitUntil((async () => {
if (self.registration.navigationPreload) {
await self.registration.navigationPreload.enable();
}
})());
});

由于设置保存在注册上,后续不再调用 enable() 的 worker 版本仍然处于预加载开启状态;要去掉它,必须显式调用 disable()。

先用 preloadResponse,再回退到 fetch()

链接到“先用 preloadResponse,再回退到 fetch()”一节

处理器先查缓存,没有命中就读预加载响应,最后再发出普通 fetch 请求。各条分支都会等待预加载 Promise,让浏览器提前发出的请求完成。

self.addEventListener('fetch', (event) => {
if (event.request.mode !== 'navigate') return;
event.respondWith((async () => {
const cached = await caches.match(event.request);
if (cached) {
event.waitUntil(event.preloadResponse); // 让预加载静静完成
return cached;
}
const preloaded = await event.preloadResponse;
if (preloaded) return preloaded;
return fetch(event.request);
})());
});

缓存命中后再 await preloadResponse 不会拖慢响应;它只是让 worker 存活到预加载落定。忽略尚未完成的预加载会让 Chrome 在页面控制台记录 The service worker navigation preload request was cancelled before 'preloadResponse' settled. If you intend to use 'preloadResponse', use waitUntil() or respondWith() to wait for the promise to settle.。

检测管理器是否存在,并在没有它时保持 fetch 处理函数正确

链接到“检测管理器是否存在,并在没有它时保持 fetch 处理函数正确”一节

Firefox 99 之前与 Safari 15.4 之前的注册对象上没有 navigationPreload,Chrome 58 及更早版本中 event.preloadResponse 是 undefined(而不是 Promise)。同一个特性检测可以处理这三种状态。

// activate:只在管理器存在时启用
self.addEventListener('activate', (event) => {
event.waitUntil(
self.registration.navigationPreload
? self.registration.navigationPreload.enable()
: Promise.resolve() // 没有预加载:导航像以前一样等待 worker
);
});
// fetch:把缺失的 preloadResponse 当作"没有预加载"
async function navigationResponse(event) {
const preloaded = event.preloadResponse ? await event.preloadResponse : undefined;
return preloaded ?? fetch(event.request);
}

回退后,每次导航都要等待 worker 启动。先在 Performance 面板测量启动时间,再决定是否改用缓存优先的应用壳;采用这种应用壳就无需预加载。

规范

规范状态
无。