12k
All articles

以 ES 模块方式编写 Service Worker

了解如何将 Service Worker 转为 ES 模块,涵盖静态导入、代码共享、构建选项、更新缓存及旧版浏览器的回退方案。

OpenReplay Team
OpenReplay Team
以 ES 模块方式编写 Service Worker

要让 Service Worker 以 ES 模块方式运行,需调用 navigator.serviceWorker.register('/sw.js', { type: 'module' })。如果不传入该选项,浏览器会将文件作为经典脚本(classic script)加载,此时 import 和 export 都会被视为语法错误。

大多数团队走到这一步的经历都差不多:应用已全面采用 ESM 并使用 Vite 构建,而 Service Worker 仍是一个经典脚本,通过 importScripts() 加载一份手动复制的配置文件,而这份文件总会与应用逐渐脱节。将 Worker 改为模块可以解决这个问题,但模块 Worker 遵循不同的规则,而且直到 Firefox 147 发布,浏览器支持才算全面到位。本文将介绍注册方式的变化、如何与页面共享代码、导致模块 Worker 出错的规则、更新机制的表现、构建产物以及降级方案。有关生命周期的基础知识,请参阅 A Practical Guide to Service Workers。

核心要点

  • 向 register() 传入 { type: 'module' } 即可将 Service Worker 作为 ES 模块运行。默认类型为 'classic'。
  • 在模块 Worker 中调用 importScripts() 会抛出 TypeError,因此所有此类调用都必须改为静态 import。
  • 动态 import() 和 import maps 在 Service Worker 中均不可用,因此所有模块说明符(specifier)都必须在构建时解析为真实的 URL。
  • 模块 Service Worker 支持 Chrome 和 Edge 91+、Safari 15+ 以及 Firefox 147+。
  • 默认的 updateViaCache: 'imports' 设置允许更新检查从 HTTP 缓存中获取导入的模块,因此应为共享模块使用带哈希的 URL,或设置较短的缓存有效期。

如何将 Service Worker 切换为 ES 模块?

将 Service Worker 切换为 ES 模块只需两处改动:注册时传入 type 选项,并将 importScripts() 替换为 import。根据 MDN 的 register() 参考文档,type 可取 'classic'(默认值)或 'module'。

以下是经典脚本版本:

// config.js (classic)
self.CACHE_NAME = 'app-v3';

// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);

以下是模块版本:

// config.js (module)
export const CACHE_NAME = 'app-v3';

// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);

模块脚本通过 CORS 加载,以严格模式运行,并且必须使用 JavaScript MIME 类型(如 text/javascript)提供,MDN 的 Worker() 构造函数页面针对模块 Worker 对此有所说明。

在页面与 Worker 之间共享代码

以 ES 模块方式编写 Service Worker 的主要理由在于,同一个模块可以同时供页面和 Worker 使用。将缓存名称和预缓存列表放在同一个文件中:

// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];

Worker 导入这两个值,并使用标准的 Cache API 调用:

// sw.js
import { CACHE_NAME, PRECACHE_URLS } from './config.js';

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
});

页面导入同一个文件:

// main.js, loaded via <script type="module">
import { CACHE_NAME } from './config.js';

console.debug('Expected cache:', CACHE_NAME);
navigator.serviceWorker.register('/sw.js', { type: 'module' });

这样,只需在一处修改版本字符串,两端都能同步获得变更。

导致模块 Service Worker 出错的三条规则

将经典 Service Worker 转换为 ES 模块时,大多数故障都源于以下三条规则。

  1. 不能使用 importScripts()。 根据 HTML 规范中 importScripts() 的处理步骤,当全局作用域的类型为 "module" 时会抛出 TypeError,而 MDN 的 importScripts() 参考文档也建议模块 Worker 改用 import。如果你的 Worker 通过 importScripts() 加载某个库,就需要该库的 ESM 构建版本。
  2. 不能使用动态 import()。 MDN 的 ServiceWorker 页面指出,规范禁止在 Service Worker 中使用动态 import(),调用时会抛出异常。对于需要按条件加载的代码,应预先通过静态导入加载。
  3. 不能使用 import maps。 import maps 在 Service Worker 内部不生效,在 Worker 中支持 import maps 目前仍是一项尚未落地的提案(whatwg/html #8173)。所有说明符都必须是相对或绝对 URL。像 'idb' 这样的裸模块名(bare specifier)无法作为模块说明符进行解析,因此必须由构建步骤对其进行改写或内联。

导入的模块如何影响 Service Worker 更新

在模块 Service Worker 中,导入的模块也会纳入更新检查。即使 sw.js 本身没有变化,对 config.js 等静态导入文件的修改同样可以触发更新流程,这与 importScripts() 依赖的处理方式一致,Chrome 发布模块 Service Worker 的公告中对此有所说明。

updateViaCache 选项决定这些检查能否使用 HTTP 缓存:

取值主脚本导入的模块
'imports'(默认)始终从网络获取允许使用 HTTP 缓存
'all'允许使用 HTTP 缓存允许使用 HTTP 缓存
'none'始终从网络获取始终从网络获取

在默认设置下,如果共享模块使用不带哈希的 URL 提供且设置了较长的 max-age,那么在更新检查中它可能一直保持旧版本。你可以使用基于内容哈希的 URL 提供共享模块、为其设置较短的缓存有效期,或者在注册时指定 updateViaCache: 'none'。如果会话回放显示部署后用户仍停留在旧版 UI,或者在请求已不存在的哈希资源,通常就意味着存在此类更新问题。调试 Service Worker 一文介绍了如何确认当前处于控制状态的 Worker 版本。

构建工具:非打包 ESM 还是单文件

Vite 将 Service Worker 视为普通的输出文件:它必须作为独立入口,输出到一个稳定的、不带哈希的 URL,例如 /sw.js。如果 URL 在每次构建时都发生变化,注册所指向的脚本也会随之改变。Vite 的 public 目录会原样复制文件而不做任何处理,这适合手写的 Worker,但不会解析其中的导入。

构建模块 Service Worker 有两种方式:

  • 非打包 ESM。 sw.js 及其共享模块作为独立文件发布,使用 URL 说明符,并通过 type: 'module' 注册。每个导入都是一次单独的请求,并且都纳入更新检查。
  • 单个打包文件。 打包工具将所有内容(包括使用裸模块名引用的包)内联到一个脚本中。如果输出中不含任何 import 语句,它也能作为经典 Worker 运行,因而可以充当降级方案。

针对不支持模块的浏览器的降级方案

根据 caniuse 上的 MDN browser-compat-data,四大浏览器引擎均已支持模块 Service Worker:

浏览器首个支持 type: 'module' 的版本
Chrome91
Edge91
Safari(macOS 和 iOS)15
Firefox147,参见 Firefox 147 发行说明

只有旧版浏览器才需要经典脚本构建:Chrome 和 Edge 90 及更早版本、Safari 14.1 及更早版本,以及 Firefox 146 及更早版本。目前没有标准 API 可以检测模块支持,w3c/ServiceWorker #1582 中的特性检测请求即说明了这一点。旧版浏览器不会预先拒绝 type 选项,而是先下载脚本,在执行失败后令 register() 返回 rejected。你可以捕获这一拒绝:

async function registerSW() {
  if (!('serviceWorker' in navigator)) return;
  try {
    return await navigator.serviceWorker.register('/sw.js', { type: 'module' });
  } catch (err) {
    console.warn('Module service worker failed, falling back to classic:', err);
    return navigator.serviceWorker.register('/sw-classic.js');
  }
}

这种 try/catch 降级方案有两方面的代价。一是旧版浏览器会白白下载一次模块脚本;二是在支持模块的浏览器中,catch 也会掩盖模块 Worker 中的真实错误,因此应在降级之前记录错误信息。

总结

将 Service Worker 转换为模块,归根结底就是 type 选项加上三条规则:只使用静态导入、不使用 importScripts()、不使用裸模块名。入手时,可以先把 Worker 和页面中重复定义的常量移到同一个共享模块中,使用 { type: 'module' } 注册,并检查该模块的缓存策略,确保对它的修改能通过更新检查送达用户。

常见问题

可以在模块 Service Worker 中使用顶层 await 吗?

不可以。Service Worker 禁止使用顶层 await,因为初始执行必须同步完成,才能及时绑定 install 和 fetch 等事件监听器。Chromium 会以 TypeError 拒绝注册。即使 await 位于某个静态导入的模块中也同样如此,因为它会使整个模块图变为异步。应将异步初始化逻辑移到 install 或 activate 处理函数中,并用 event.waitUntil() 包裹。

在同一 URL 下将现有 Service Worker 从经典脚本切换为模块,会触发更新吗?

会。Service Workers 规范将 Worker 类型的变更视为一次更新,即使脚本 URL 及其内容完全相同。在已有经典注册的基础上调用 register('/sw.js', { type: 'module' }) 会安装一个新的 Worker,随后它将经历正常的等待和激活生命周期。而如果 register() 调用的 URL、type 和 updateViaCache 值都相同,则会直接 resolve,不会发起任何请求。

模块 Service Worker 可以从 CDN 或其他源导入模块吗?

可以,前提是对方源允许。模块导入通过 CORS 获取,因此跨源模块必须附带允许你的源的 Access-Control-Allow-Origin 响应头,否则导入会失败,register() 也会被拒绝。经典的 importScripts() 调用则无此要求,因为它以 no-cors 模式加载脚本。不过,Service Worker 脚本本身仍必须与注册它的页面同源。

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.