前端 Cache API 如何按版本清理离线资源：请求匹配、缓存更新与失效回滚

离线页面最难排查的故障，往往不是“没有缓存”，而是新旧资源同时存在：HTML 已经更新，旧版 JavaScript 还在 Cache Storage 里，用户刷新后拿到一套互相不匹配的文件。Cache API 只提供存取能力，版本命名、更新顺序、清理范围和失败回退都要由应用自己定义。

把缓存名当成一次可回滚的发布版本：先完整建立新缓存，确认成功后再清理旧版本；任何一步失败，都保留上一版可用资源。

先划清 Cache API 的保护边界

Cache Storage 可以通过 caches.open() 获取命名缓存，也可以用 caches.match() 在受管缓存中查找请求，用 caches.delete() 删除一个完整缓存。它适合保存静态脚本、样式、字体和明确允许离线读取的公开接口响应，不适合保存访问令牌、支付状态或需要实时一致性的库存数据。

这些接口通常运行在安全上下文中。开发阶段如果直接用不受信任的 HTTP 地址测试，可能先遇到权限或可用性问题；先用本地 HTTPS 或浏览器支持的安全开发环境确认问题来源，别把环境限制误判成缓存逻辑错误。

用版本缓存隔离一次完整资源发布

版本名是清理策略的锚点。下面把资源列表和版本号放在同一个 Service Worker 文件中，示例只缓存三类静态资源；实际项目应按构建产物清单生成，不要手写一个已经过期的文件名。

const CACHE_NAME = 'app-static-v3';
const ASSETS = [
  '/',
  '/index.html',
  '/assets/app.js'
];

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

cache.addAll 会逐个获取资源并写入缓存，资源请求或响应不满足要求时，整个准备过程会失败。这里的失败很有价值：它阻止一个缺文件的新版本被当成完整离线版本使用。不要为了“尽量缓存”而吞掉异常，否则激活后才发现入口脚本缺失，回滚会更麻烦。

新缓存完整成功后再清理旧版本

清理动作放在 activate 阶段，但不能见到旧名字就全部删除。浏览器里可能同时存在别的应用缓存，规则应该先检查前缀，再排除当前版本。这样即使某个旧缓存删除失败，当前版本仍然有机会继续工作。

self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    const keys = await caches.keys();

    await Promise.all(keys.map((key) => {
      if (key.startsWith('app-static-') && key !== CACHE_NAME) {
        return caches.delete(key);
      }
      return Promise.resolve(false);
    }));
  })());
});

如果发布过程中发现新资源清单有误，只要新缓存没有完整建立，就不要主动删除旧缓存。对清理结果也不要做过度解读：caches.delete 返回 true 表示找到并删除，返回 false 表示目标不存在，两者都不等于“页面已经在线更新”。页面是否接管、是否刷新，还要结合 Service Worker 生命周期单独验收。

读取路径要能从缓存退回网络

安装缓存解决的是“准备什么”，读取策略解决的是“请求时信任什么”。静态资源可以优先使用缓存；未命中时请求网络，网络成功后写入当前版本缓存。写入前先复制响应，避免消费掉即将返回给页面的响应体。

self.addEventListener('fetch', (event) => {
  event.respondWith((async () => {
    const cached = await caches.match(event.request);
    if (cached && cached.ok) {
      return cached;
    }

    const response = await fetch(event.request);
    if (response.ok && event.request.method === 'GET') {
      const cache = await caches.open(CACHE_NAME);
      await cache.put(event.request, response.clone());
    }
    return response;
  })());
});

这段路径只把成功的 GET 响应写入缓存。POST 请求、跨源的不可用响应、带用户隐私的接口，都不应该因为“能写进去”就进入离线缓存。离线状态下既没有缓存也没有网络响应时，应该返回项目准备好的离线页或清晰的错误状态，而不是把异常伪装成旧数据。

把失败与回滚写进验收路径

安全的升级流程至少要验证四个结果：新缓存全部资源可读取；旧版本只在新版本准备完成后清理；非本应用缓存不受影响；网络不可用时，已缓存的静态资源仍能打开。测试时可以在开发者工具的 Application 面板查看 Cache Storage，在 Network 面板切换离线，再刷新入口页。

最容易遗漏的是“半更新”：构建产物中的 /assets/app.js 已改名，但资源清单仍指向旧文件。安装失败时应保留旧缓存；如果页面已经进入新 Service Worker，再由应用展示更新失败状态并允许重试。不要把清理旧缓存放在安装开始前，那会把原本可用的回滚路径提前删掉。

常见问题

为什么改了文件但用户仍拿到旧 JavaScript？

常见原因是缓存名没有变化，或者激活阶段没有删除旧版本。先在 Cache Storage 中确认当前版本名和资源内容，再检查 Service Worker 是否已经完成更新与接管。

可以直接调用 caches.delete 清空所有缓存吗？

不建议。只删除带有本应用前缀且不是当前版本的缓存，避免误伤同源下其他功能或其他应用留下的缓存。

cache.addAll 失败后应该忽略错误吗？

对于必需离线资源不应忽略。让安装阶段失败并保留旧版本，通常比激活一个缺入口脚本的新版本更容易恢复。

Cache API 能替代后端数据缓存吗？

不能。它是浏览器端请求与响应存储机制，适合离线资源和明确的读取策略；权限、库存、订单等数据仍以服务端规则和实时响应为准。

版本化缓存的核心不是多写几个字符串，而是让“准备、读取、清理、失败”各自有清楚的边界。先建立完整的新缓存，再清理旧版本；读取时保留网络回退和离线提示，发布问题就不会被一堆无法解释的旧文件掩盖。