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

# 背景与价值 - 直接使用 Cache API 进行离线缓存与精细化控制，搭配版本与失效策略提升稳定性。 # 版本化缓存命名 ```ts const STATIC_CACHE = 'static-v3'; const API_CACHE = 'api-v1'; ``` # 安装与预缓存 ```ts self.addEventListener('install', (event: ExtendableEvent) => { event.waitUntil((async () => { const cache = await caches.open(STATIC_CACHE); await cache.addAll(['/index.html', '/styles.css', '/app.js']); })()); }); ``` # 激活与旧版本清理 ```ts 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(); })()); }); ``` # 路由与冲突解决 ```ts 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 请求回退稳定，冲突解决正确。