以 ES 模块方式编写 Service Worker
了解如何将 Service Worker 转为 ES 模块,涵盖静态导入、代码共享、构建选项、更新缓存及旧版浏览器的回退方案。
要让 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 模块时,大多数故障都源于以下三条规则。
- 不能使用
importScripts()。 根据 HTML 规范中importScripts()的处理步骤,当全局作用域的类型为"module"时会抛出TypeError,而 MDN 的importScripts()参考文档也建议模块 Worker 改用import。如果你的 Worker 通过importScripts()加载某个库,就需要该库的 ESM 构建版本。 - 不能使用动态
import()。 MDN 的ServiceWorker页面指出,规范禁止在 Service Worker 中使用动态import(),调用时会抛出异常。对于需要按条件加载的代码,应预先通过静态导入加载。 - 不能使用 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' 的版本 |
|---|---|
| Chrome | 91 |
| Edge | 91 |
| Safari(macOS 和 iOS) | 15 |
| Firefox | 147,参见 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 脚本本身仍必须与注册它的页面同源。