必须拆开用IndexedDB管业务数据、Cache API管静态资源：前者支持结构化查询与事务，后者可拦截网络请求缓存资源；二者共用Service Worker生命周期但数据隔离，避免混存导致的TypeError或性能问题。
用 IndexedDB + Cache API 组合解决离线读写与资源缓存分离问题
纯用 Cache API 无法支持结构化查询和本地事务，纯用 IndexedDB 又没法拦截网络请求做资源缓存——必须拆开用：Cache API 管静态资源（HTML/CSS/JS/图片），IndexedDB 管业务数据（用户笔记、表单草稿、消息列表）。两者共用一个 Service Worker 生命周期，但数据不混存。
常见错误是试图把 JSON 数据塞进 Cache API，结果遇到 TypeError: Request destination is not 'document' or 'subresource'；或者把图片二进制 blob 存进 IndexedDB，导致打开慢、GC 压力大。
- 静态资源走
caches.open('static-v1')，用cache.addAll()预缓存关键路径，如['/', '/index.html', '/assets/main.js'] - 业务数据用 IndexedDB 存对象仓库（objectStore），主键设为
id，加索引字段如updatedAt和syncStatus（值为'pending'/'synced'/'failed'） - Service Worker 中拦截 fetch 时，优先查 Cache API（对 GET 资源），再 fallback 到网络；对 POST/PUT 请求，则直接转发，由前端逻辑决定是否写入 IndexedDB
增量同步靠时间戳 + 状态标记，别依赖自增 ID
后端返回的 lastModified 或 updatedAt 字段才是可靠同步依据。自增 ID 在多端编辑、离线插入、数据库迁移时极易冲突，syncStatus: 'pending' 字段必须配合服务端幂等接口（如用 X-Request-ID 去重）。
典型坑是前端只比对本地最大 id，结果离线期间别人删了一条记录，你同步时漏掉删除操作；或者没处理服务端 409 Conflict，导致本地状态卡在 'pending' 不动。
- 同步前先查 IndexedDB：
transaction.objectStore('notes').index('updatedAt').openCursor(IDBKeyRange.lowerBound(lastSyncTime), 'prev')，反向遍历拿到最新变更 - 每条待同步记录带
op: 'create' | 'update' | 'delete'字段，服务端按 op 类型执行，成功后更新本地syncStatus和serverId - 失败时记录
errorCount，超过 3 次自动降级为手动触发同步，并在 UI 显示「有 2 条未同步」提示
Service Worker 更新后，旧缓存和 DB 版本要主动清理
新版 SW 安装时，旧版 caches.keys() 返回的缓存名还在，旧版 IndexedDB 的 onupgradeneeded 也不会自动触发——必须显式清理，否则用户永远用不到新缓存策略，或 DB schema 错乱。
最容易被忽略的是：缓存清理必须在 activate 事件里做，不能放在 install；而 DB 版本升级必须在 onupgradeneeded 中完成，且不能跳版本（v1 → v3 要经过 v2）。
- 在
self.addEventListener('activate', e => { ... })中调用caches.keys().then(keys => Promise.all(keys.map(k => k.startsWith('static-') && k !== 'static-v2' ? caches.delete(k) : null))) - 打开 DB 时指定新版 version：
indexedDB.open('myapp-db', 2)，并在onupgradeneeded中检查event.oldVersion，逐级迁移（if (oldVersion →if (oldVersion ） - 迁移完成后，用
transaction.objectStore('notes').clear()清空测试数据（仅开发期），生产环境改用条件迁移
调试离线行为必须关掉 Chrome 的“Update on reload”
DevTools 的 Application → Service Workers 面板里勾选了 Update on reload，会导致每次刷新都跳过 cache、绕过 fetch 事件监听，你以为离线逻辑没问题，其实根本没跑。
真实离线测试三步缺一不可：1）关闭该选项；2）点 Offline 开关；3）硬刷新（Ctrl+F5 或 Cmd+Shift+R），避免从内存缓存加载。
- 验证 Cache API 是否生效：Network 面板中查看资源 Size 列是否显示
from ServiceWorker或from Cache - 验证 IndexedDB 写入：Application → Storage → IndexedDB，点开数据库看 objectStore 数据是否实时更新（注意：部分浏览器需刷新面板才更新）
- 模拟同步失败：在 Service Worker 的
fetch事件中对特定 URLreturn new Response('', {status: 500})，观察本地syncStatus是否正确置为'failed'
离线数据库最难的不是存数据，是让「网络恢复那一刻」的行为可预测——同步队列是否清空、冲突是否提示、UI 状态是否及时反馈，这些细节全藏在 SW 的 activate/fetch/message 事件边界里。
