---

title: Cache API 离线缓存与一致性治理：版本化、失效与冲突解决实践

tags: [Cache API, caches, 离线缓存, 版本化, 失效治理]

description: 使用 Cache API 在 Service Worker 中实现离线缓存与版本治理，处理失效与冲突，提升命中率与一致性，并提供验证指标与测试清单。

categories:

• 文章资讯
• 技术教程

---

背景与价值

• 直接使用 Cache API 进行离线缓存与精细化控制，搭配版本与失效策略提升稳定性。

版本化缓存命名

const STATIC_CACHE = 'static-v3';
const API_CACHE = 'api-v1';

安装与预缓存

self.addEventListener('install', (event: ExtendableEvent) => {
  event.waitUntil((async () => {
    const cache = await caches.open(STATIC_CACHE);
    await cache.addAll(['/index.html', '/styles.css', '/app.js']);
  })());
});

激活与旧版本清理

self.addEventListener('activate', (event: ExtendableEvent) => {
  event.waitUntil((async () => {
    const keys = await caches.keys();
    await Promise.all(keys.filter(k => ![STATIC_CACHE, API_CACHE].includes(k)).map(k => caches.delete(k)));
    await (self as any).clients.claim();
  })());
});

路由与冲突解决

self.addEventListener('fetch', (event: FetchEvent) => {
  const url = new URL(event.request.url);
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(networkFirst(event.request));
  } else {
    event.respondWith(cacheFirst(event.request));
  }
});

async function cacheFirst(req: Request) {
  const cache = await caches.open(STATIC_CACHE);
  const hit = await cache.match(req);
  if (hit) return hit;
  const res = await fetch(req);
  if (res.ok) cache.put(req, res.clone());
  return res;
}

async function networkFirst(req: Request) {
  const cache = await caches.open(API_CACHE);
  try {
    const res = await fetch(req);
    if (res.ok) cache.put(req, res.clone());
    return res;
  } catch {
    const hit = await cache.match(req);
    if (hit) return hit;
    return new Response('offline', { status: 503 });
  }
}

指标验证（Chrome 128/Edge 130）

• 静态命中率：≥ 90%；API 离线回退成功率 ≥ 97%。
• 一致性：版本切换后错误内容率 ≤ 0.3%。
• 稳定性：长驻 24h 无缓存膨胀与冲突失效问题。

测试清单

• 版本升级：旧缓存清理正确；离线路径仍可用。
• 弱网场景：API 请求回退稳定，冲突解决正确。