PWA离线数据库设计与同步方案解析

本文深入剖析了PWA离线数据库设计的核心实践，强调必须严格分离IndexedDB（专管结构化业务数据，支持事务与查询）和Cache API（专管静态资源，可拦截网络请求），二者协同Service Worker生命周期却绝不混存，以规避TypeError、性能劣化与同步混乱；文章直击开发常见陷阱——如误用Cache API存储JSON、用自增ID做同步依据、忽略SW更新时的缓存与DB版本清理，并给出可落地的增量同步方案（基于时间戳+操作类型+幂等接口）、精准调试方法（禁用Update on reload、硬刷新验证）以及生产级健壮性保障细节，真正解决“网络恢复那一刻”行为不可控这一离线体验最大痛点。

用 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 事件中对特定 URL return new Response('', {status: 500})，观察本地 syncStatus 是否正确置为 'failed'

离线数据库最难的不是存数据，是让「网络恢复那一刻」的行为可预测——同步队列是否清空、冲突是否提示、UI 状态是否及时反馈，这些细节全藏在 SW 的 activate/fetch/message 事件边界里。

理论要掌握，实操不能落！以上关于《PWA离线数据库设计与同步方案解析》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！