浏览器 Cache API 更新资源时如何清理旧版本

我在给静态资源加 service worker 缓存时，最容易踩的坑不是“缓存没写进去”，而是新版本已经生成，却仍然从旧缓存里拿到 app.js。浏览器不会因为 service worker 更新就自动删除旧 Cache。可靠做法是给每轮资源使用不同的缓存名：新版本在 install 中写入，等它进入 activate 后，用白名单枚举并删除旧缓存。这里删除的是整个命名缓存，不能把 Cache.delete() 和 caches.delete() 混为一谈。

先分清要清理的是哪一层

Cache API 有两层对象。CacheStorage 由全局的 caches 表示，里面管理多个有名字的缓存；Cache 是通过 caches.open("static-v2") 得到的单个容器，里面存放请求和响应对。

所以，更新资源版本时先调用 caches.keys() 找到容器名称，再把不在保留名单里的名称交给 caches.delete()。如果只调用 cache.delete("/app.js")，其他旧文件仍会留在原缓存中。

install 写入新版本，activate 清理旧版本

下面的示例把当前资源缓存命名为 static-v3。新 worker 安装时只创建新容器；清理动作放到激活阶段，避免旧 worker 还在为已打开页面提供服务时，突然删掉它依赖的缓存。

const CURRENT_CACHE = "static-v3";
const ASSETS = ["/", "/app.js", "/styles.css"];

self.addEventListener("install", (event) => {
  event.waitUntil((async () => {
    // 先把新版本资源写入独立容器，避免覆盖旧 worker 正在使用的内容。
    const cache = await caches.open(CURRENT_CACHE);
    await cache.addAll(ASSETS);
  })());
});

self.addEventListener("activate", (event) => {
  event.waitUntil((async () => {
    // 白名单只保留当前版本，避免误删同源下不属于本应用的缓存。
    const keep = new Set([CURRENT_CACHE]);
    const names = await caches.keys();
    await Promise.all(
      names
        .filter((name) => !keep.has(name))
        .map((name) => caches.delete(name)),
    );
  })());
});

event.waitUntil() 会把异步清理纳入 activate 事件；清理结束后再让新版本继续处理后续工作。生产环境不要把缓存名写成模糊的“全部清空”，尤其是多个应用共用一个 origin 时，精确白名单更安全。

更新不生效时，按生命周期和命中范围排查

看到旧文件并不一定说明 caches.delete() 失败。先记录 await caches.keys() 的返回值：没有 static-v3，说明新版本安装或预缓存失败；旧名仍存在，才进入清理逻辑检查。若旧页面仍由旧 worker 控制，新 worker 可能还在 waiting 状态，不能用“刷新一次”推断清理已经完成。

读取资源时也尽量打开明确的当前缓存：

self.addEventListener("fetch", (event) => {
  event.respondWith((async () => {
    // 只在当前版本容器中查找，避免跨版本匹配到旧响应。
    const cache = await caches.open(CURRENT_CACHE);
    const cached = await cache.match(event.request);
    if (cached) return cached;
    return fetch(event.request);
  })());
});

直接使用全局 caches.match() 会在多个缓存中寻找匹配项，版本切换期间更难判断命中了哪一份资源。调试时可以把缓存名称、worker 状态和资源 URL 一起记录，而不是只看页面最终显示的文件。

上线前的缓存清理检查清单

• 缓存名是否随资源版本变化，且当前版本只有一个明确入口。
• 清理是否放在 activate，并通过 event.waitUntil() 等待完成。
• 是否只删除自己的缓存名，避免影响同源的其他应用。
• fetch 是否明确打开当前缓存，避免跨版本的隐式匹配。
• 是否保留回滚策略：回滚到旧 worker 时，旧缓存名仍能按计划恢复。

相关问题

Cache API 会自动更新服务器上的同名文件吗？

不会。缓存中的响应不会因为服务器文件变更自动替换，需要在新的 worker 或明确的更新策略中重新写入。

caches.delete() 返回 false 是错误吗？

不一定。它表示指定名称当时不存在；可以把它当作幂等清理结果，但仍应检查缓存名是否拼写正确。

为什么不在 fetch 事件里直接删除旧缓存？

fetch 可能同时服务多个请求，清理时机不稳定。版本淘汰更适合放在 activate，并让事件等待清理完成。