Service Worker缓存版本切换与旧缓存清理流程

前端发布后页面仍显示旧资源，通常不是“浏览器没有更新”，而是新旧 Service Worker 正处在不同生命周期。稳妥的切换方式是：install 阶段写入带新版本号的缓存，activate 阶段只删除白名单之外的旧缓存，再决定是否让新 Worker 立即接管页面。这样旧页面还有机会使用旧资源，新版本也不会在安装中途覆盖它。

先把新缓存与旧缓存隔离

缓存切换的第一步不是删除 assets-v1，而是先创建 assets-v2。更新中的 Worker 安装时，旧 Worker 仍可能为已经打开的页面处理请求；如果两个版本共用一个缓存名，旧页面可能读到新格式的 JSON 或缺少兼容字段的脚本。把版本号放入缓存名，就能让两套资源在切换窗口内互不覆盖。

const CACHE_NAME = "assets-v2";
const PRECACHE_URLS = ["/", "/index.html", "/assets/app.v2.js"];

self.addEventListener("install", (event) => {
  // 新版本先写入独立缓存；失败时不要让半套资源进入可用状态。
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS)),
  );
});

这里的 waitUntil 让安装结果跟随预缓存 Promise：资源全部加入才算安装成功，任一关键资源失败就不会把这次安装当成完整版本。静态资源命名也要和构建产物一致，不能只改缓存常量而继续指向旧的入口文件。

在 activate 阶段按白名单删除旧缓存

新 Worker 成功安装后不一定马上激活，因此删除旧缓存应放在 activate。清理逻辑不要只写“删除上一个版本”，而应维护一个保留集合：除了当前静态资源缓存，还可以保留头像、离线文档等跨版本缓存。caches 属于当前 origin 的存储，多个站点共用 origin 时还要给缓存名加项目专属前缀。

const KEEP_CACHES = new Set(["app-assets-v2", "app-avatar"]);

self.addEventListener("activate", (event) => {
  // activate 完成前暂缓新的功能事件，避免 fetch 读到刚删除的旧资源。
  event.waitUntil(
    caches.keys().then((cacheNames) =>
      Promise.all(
        cacheNames
          .filter((name) => name.startsWith("app-") && !KEEP_CACHES.has(name))
          .map((name) => caches.delete(name)),
      ),
    ),
  );
});

过滤条件有两个作用：只触碰本项目的缓存，并且只删除不在白名单中的版本。CacheStorage.delete() 返回 Promise，配合 event.waitUntil() 后，激活阶段的清理完成才会继续进入稳定的 fetch 处理。

决定是否立即接管页面

默认生命周期会让新 Worker 先处于 waiting，等旧页面不再使用旧 Worker 后再激活。这种方式更保守，适合页面脚本与缓存资源必须成套发布的应用。若新旧资源协议完全兼容，才考虑在安装结束时调用 self.skipWaiting()，并在激活时调用 clients.claim() 让已有页面更快被新 Worker 控制。

self.addEventListener("install", (event) => {
  // 只有新旧页面可以读取同一套资源协议时，才提前跳过 waiting。
  self.skipWaiting();
});

self.addEventListener("activate", (event) => {
  // 清理逻辑完成后再接管已打开的页面，页面端监听 controllerchange。
  event.waitUntil(clients.claim());
});

提前接管的风险在于：旧页面的 JavaScript 可能已经加载，却突然由新 Worker 返回新接口或新资源。若页面没有版本握手、兼容字段或刷新提示，容易出现“脚本和数据格式不匹配”。更稳的做法是保留 waiting，在页面收到 controllerchange 后提示刷新，或先灰度一小部分用户。

用发布检查清单验证切换结果

上线前可以按下面的表格复查。重点不是缓存数量越少越好，而是每个缓存的所有者、生命周期和回滚路径都清楚。

实际排查时先看注册对象的 installing、waiting、active 状态，再看缓存键是否符合白名单。若新版本一直 waiting，优先确认仍有页面被旧 Worker 控制，不要直接把清理逻辑挪到 install。

常见问题

为什么只改缓存名，旧缓存还在？

改名只会创建新缓存，不会自动删除旧缓存。必须在新 Worker 的 activate 中枚举缓存并删除白名单之外的项目。

可以在 install 里删除旧缓存吗？

不建议。旧 Worker 可能仍在服务已打开页面，install 阶段删除旧缓存会破坏它依赖的资源；activate 才是更合适的清理边界。

skipWaiting 一定能让页面立刻更新吗？

它只会缩短 Worker 的等待阶段，页面是否已经被新 Worker 控制还取决于接管时机。使用 clients.claim 后仍应监听 controllerchange，并处理刷新或资源兼容问题。