Service Worker 缓存策略的版本更新方法

Service Worker 缓存更新的关键，不是每次发布都把缓存清空，而是让“代码版本、缓存名称、清理规则和回滚策略”保持同一套约定。推荐给缓存名加上发布版本，例如 app-static-v3，新版本在 install 中先建立自己的缓存，等它进入 activate 后再清理明确属于本应用的旧缓存。

这样做的好处是：旧页面仍由旧 worker 服务时，旧缓存不会被新 worker 提前删除；新版本预缓存失败时，也不会半成品接管请求。

先把 cache key 设计成发布版本

Cache API 的缓存对象由字符串名称区分，建议把应用前缀、资源用途和发布版本拆开表达。静态资源和运行时资源不要共用一个名字，否则后续很难判断哪些条目可以删除。

// 版本号与资源用途一起组成稳定的缓存键，发布时只改版本号。
const RELEASE = "v3";
const STATIC_CACHE = `app-static-${RELEASE}`;
const RUNTIME_CACHE = `app-runtime-${RELEASE}`;
const CACHE_PREFIX = "app-";

// 只让当前版本参与预缓存，运行时缓存按同一版本隔离。
const PRECACHE_URLS = ["/", "/index.html", "/app.js", "/styles.css"];

不要用随机数作为 cache key。随机 key 会让每次 worker 启动都产生新缓存，也让清理和回滚失去确定性。版本号可以是构建号、提交号或人工维护的发布标识，但同一次发布中的 worker 和资源清单必须一致。

install 阶段先准备新缓存

新 worker 安装时，旧 worker 仍可能控制已经打开的页面。把预缓存放进 event.waitUntil()，并让 cache.addAll() 的失败直接使安装失败，可以避免一个缺少关键资源的版本进入下一阶段。

self.addEventListener("install", (event) => {
  event.waitUntil((async () => {
    // 新版本写入自己的缓存，不修改旧版本正在使用的内容。
    const cache = await caches.open(STATIC_CACHE);
    await cache.addAll(PRECACHE_URLS);

    // 是否立即跳过等待要由发布策略决定，默认保留平滑切换。
    // self.skipWaiting();
  })());
});

默认情况下，新 worker 会等待旧 worker 不再控制页面后才激活。若直接调用 skipWaiting()，再配合 clients.claim()，更新会更快，但当前页面可能突然切换到新资源，必须确保 HTML、脚本和接口协议可以跨版本共存。

activate 阶段只清理自己拥有的旧缓存

activate 是清理旧缓存的合适位置。清理动作要使用 waitUntil() 延长事件生命周期，并先用应用前缀过滤，避免误删同源下其他模块或其他团队维护的 CacheStorage。

self.addEventListener("activate", (event) => {
  event.waitUntil((async () => {
    const keep = new Set([STATIC_CACHE, RUNTIME_CACHE]);
    const keys = await caches.keys();

    // 只删除本应用且不在保留清单中的版本，其他缓存交给它们自己管理。
    await Promise.all(
      keys
        .filter((key) => key.startsWith(CACHE_PREFIX) && !keep.has(key))
        .map((key) => caches.delete(key)),
    );

    // 只有确认页面可以无感切换时才开启；否则等待下一次导航更稳妥。
    // await self.clients.claim();
  })());
});

这里的重点是“保留清单”，而不是简单删除所有不等于当前版本的缓存。如果上线策略要求新旧页面短时间并存，就把上一版本缓存也放入清单；如果确认切换完成且不需要回滚，再在后续发布中删除它。

注册端控制 worker 脚本的更新路径

缓存资源和 worker 脚本的更新是两件事。注册时可以使用 updateViaCache 控制浏览器更新 worker 脚本时是否参考 HTTP 缓存；例如希望主脚本和它的导入脚本都绕过 HTTP 缓存，可以使用 none。

if ("serviceWorker" in navigator) {
  navigator.serviceWorker
    .register("/sw.js", {
      // 让 worker 脚本更新不依赖 HTTP 缓存中的旧副本。
      updateViaCache: "none",
    })
    .then(async (registration) => {
      // 主动检查更新；真正切换仍遵循 worker 的安装与激活生命周期。
      await registration.update();
      console.log("Service Worker update checked", registration.updateViaCache);
    })
    .catch((error) => {
      // 注册失败时保留页面自己的网络降级路径，不阻塞首屏渲染。
      console.error("Service Worker registration failed", error);
    });
}

updateViaCache 只影响 worker 脚本及其导入脚本，不会替你决定 fetch 事件中业务资源的缓存策略。生产环境还需要用正确的 HTTP 缓存头、构建产物指纹和 worker 内的版本化 cache key 配合。

需要回滚时不要先删掉上一版本

回滚不是把 caches.delete() 再调用一次。若新版本在 activate 里已经删除上一版本缓存，即使把脚本改回旧代码，也可能还要重新下载全部资源。更稳的做法是为发布保留一个短期回滚窗口。

// 回滚窗口内同时保留当前和上一版本，稳定后再由下一次发布删除旧缓存。
const ACTIVE_RELEASE = "v3";
const PREVIOUS_RELEASE = "v2";
const KEEP_CACHE_NAMES = new Set([
  `app-static-${ACTIVE_RELEASE}`,
  `app-runtime-${ACTIVE_RELEASE}`,
  `app-static-${PREVIOUS_RELEASE}`,
  `app-runtime-${PREVIOUS_RELEASE}`,
]);

// 回滚发布时，把 ACTIVE_RELEASE 改回 v2，并让 worker 与资源清单一起回退。
function shouldKeepCache(cacheName) {
  // 前缀判断避免把其他应用的同源缓存纳入回滚范围。
  return cacheName.startsWith("app-") && KEEP_CACHE_NAMES.has(cacheName);
}

发布流程可以把当前 worker、上一版本 worker、当前缓存、上一版本缓存和保留清单视为一组。发现新版本异常时，回滚同一组中的 worker 与资源版本；确认稳定后，再发布一次清理版本。不要把“用户手动清空站点数据”当成正式回滚步骤，它会同时丢失离线能力和其他有效缓存。

一份可落地的更新清单

Service Worker 版本更新的最小闭环可以概括为：新版本先写新 cache key，安装成功后再激活；激活时只清理自己确认过期的缓存；发布平台保留上一版本 worker 和缓存，稳定后再清理。这样 cache key、activate 和回滚是同一套发布设计，而不是三个互相独立的补丁。

常见问题

为什么改了缓存名，浏览器仍然没有马上使用新 worker？

新 worker 需要经历安装、等待和激活，旧页面仍被旧 worker 控制时不会立刻切换。检查注册对象的 installing、waiting 和 active 状态，并根据页面兼容性决定是否使用 skipWaiting() 与 clients.claim()。

activate 里能不能直接删除所有旧缓存？

可以删除本应用明确拥有且不再需要的旧缓存，但不应无条件删除 CacheStorage 中的全部名称。至少使用应用前缀和保留清单做范围限制。

updateViaCache 能不能解决接口响应缓存过期？

不能。它只控制 Service Worker 脚本及其导入脚本更新时如何使用 HTTP 缓存；接口响应是否缓存、何时更新，仍由 fetch 处理逻辑和服务器响应头决定。