HTML IndexedDB离线存储思路解析

一提到离线存储，很多开发者第一反应就是 IndexedDB。但这里有个关键认知需要厘清：IndexedDB 本身并不直接解决“离线存储”问题。它的核心职责是“本地结构化数据存哪、怎么查”。真正让一个网页应用在断网后依然能跑起来的，是它和 Service Worker、Cache API 这套组合拳的配合方式。

IndexedDB.open() 为什么关网后还报错？

你可能会遇到这种情况：明明已经离线了，调用 indexedDB.open() 却报错 Uncaught DOMException: Failed to execute 'open' on 'indexedDB': access is denied，或者干脆静默失败，没有任何反应。

这其实不是网络问题，而是浏览器出于安全和隐私考虑的策略拦截。具体来说，主要有以下几个原因：

• HTTPS 缺失：除了 localhost 开发环境，如果页面没有通过 HTTPS 加载，部分浏览器（尤其是 Safari）会直接拒绝 IndexedDB 的访问请求。
• 缺少用户交互：iOS Safari 等浏览器要求，首次打开数据库的操作必须由用户手势（如点击、触摸）触发。如果是页面自动加载的 PWA 启动页，没有用户交互，就可能被静默降级或拒绝。
• 隐私模式限制：在无痕或隐私模式下，IndexedDB 通常是临时的，关闭窗口数据即清空，且首次写入操作可能受到限制。
• 非法数据库名或版本号：数据库名包含斜杠、空格等非法字符，或者版本号不是正整数，都会导致打开失败。例如 indexedDB.open("my-db/v1", 1) 就会因为名称中的斜杠而出错。

正确的做法是：确保在用户点击等手势事件后，再首次调用 indexedDB.open()；使用 na vigator.storage.estimate() 预先检查存储配额；并且一定要对 onblocked（数据库版本升级被其他标签页阻塞）和 onerror 事件进行显式处理，不要只依赖 onsuccess。

Service Worker 不注册，IndexedDB 再多也没用

一个典型的误区是：代码里写好了 indexedDB.open()，离线时也能把草稿数据存进去，但一断网刷新页面，直接白屏。问题出在哪？

答案是：HTML、CSS、JS 这些核心资源根本没加载进来。Service Worker 才是离线应用的入口，必须让它先把“地基”打好。

• 注册时机：Service Worker 的注册必须在页面加载完成后的 Ja vaScript 中执行。如果放在 defer 脚本里，却没有用 await na vigator.serviceWorker.register() 等待注册完成，可能导致注册失败或延迟。
• 缓存本质：Cache API 缓存的是“请求-响应对”，而不是文件路径。执行 cache.add("/app.css") 的本质，是浏览器发起一次 GET 请求，然后把响应体存下来。
• HTML 是必须项：HTML 文件必须被显式缓存（例如 cache.addAll(["/", "/index.html"])）。否则断网后，连运行 Ja vaScript 的环境都没有，indexedDB.open() 这行代码根本不会执行。
• 谨慎使用 fallback：不要在 Service Worker 的 fetch 事件里，简单粗暴地将所有未缓存的请求都回退到缓存。对于未缓存的 API 请求，应该选择透传到网络，或者返回 503 状态码，避免掩盖真实的网络或服务器错误。

一句话总结：没有 Service Worker，IndexedDB 就是一座数据孤岛；而没有缓存 HTML，这座岛连船都开不过去。

离线写入后怎么同步？别靠定时轮询

另一个常见的坑是同步逻辑。很多应用监听 online 事件，一旦触发就立刻遍历所有待同步记录，全量提交到服务器。结果呢？服务端重复插入、前端事务中断、数据状态一片混乱。

设计一个健壮的同步机制，有几个关键点：

• 状态管理：为每条离线记录增加一个同步状态字段，如 syncStatus: "pending" | "syncing" | "success" | "failed"。任何状态变更都必须放在 IndexedDB 事务中完成，保证原子性。
• 双触发机制：同步逻辑应封装为独立函数，由 online 事件和定时检查（例如每30秒）共同触发。这样可以避免漏掉那些短暂恢复的网络窗口。
• 失败处理：当 fetch 请求失败时，在 catch 中只将记录状态更新为 "failed"，不要删除原始数据。下次重试前，先查询状态为 "failed" 的记录，避免覆盖掉用户离线期间新产生的数据。
• 服务端幂等：这是同步可靠性的基石。服务端接口必须支持幂等操作，例如 PostgreSQL 可以使用 INSERT ... ON CONFLICT DO NOTHING 语法，或者要求客户端生成全局唯一 ID（如 UUID v4）来避免主键冲突。
• 异步分片：避免在 UI 主线程进行大批量数据同步。可以使用 Web Worker，或者用 setTimeout(..., 0) 进行分片处理，防止长时间阻塞页面渲染。

记住，同步不是“一连上网就把所有数据全发一遍”，而是“每次只处理一批、带着明确状态、可以安全中断、并且能够重新进入”的精细过程。

移动端特别是 iOS Safari 的硬限制必须提前测

移动端，尤其是 iOS Safari，对 IndexedDB 有两道硬门槛：单个数据库容量上限约为 50MB，以及首次写入操作必须由用户手势触发。很多问题在开发阶段发现不了，因为开发机通常用的是 Chrome。

针对移动端的实操建议：

• 真机测试：必须包含 iOS Safari 真机测试（而非模拟器），特别是对于地图瓦片、富文本附件等大体积数据存储场景。
• 配额监控：写入前务必调用 na vigator.storage.estimate() 检查。当 usage / quota > 0.75 时，就应该主动清理旧数据，例如通过游标按时间戳 timestamp 删除最早的一批记录。
• 存储优化：对于瓦片类二进制数据，优先使用 ArrayBuffer 存储，而不是 Blob。读取时再用 URL.createObjectURL(new Blob([buf], {type})) 生成对象 URL 供图片使用，这样可以避免 Canvas 内存污染等问题。
• 版本升级兼容：在 onupgradeneeded 事件中创建好新的索引，但不要把依赖新 schema 的查询逻辑直接写在 onsuccess 里。因为旧版本的标签页可能还在运行，直接查询新字段会导致错误。

最容易忽略的一点是：离线存储的挑战，往往不在于“能不能存进去”，而在于“存进去之后，下次打开应用时，还能不能安全、正确地读出来”。数据库 schema 升级、跨标签页的版本阻塞、以及系统内存压力下的数据丢失——这些异常情况，比单纯的容量超限更常导致离线功能静默失效，需要格外关注。