HTML IndexedDB离线存储教程

本文深入剖析了HTML中IndexedDB在离线场景下的常见误区与实战要点，明确指出IndexedDB本身只是本地数据库而非“离线存储方案”，真正决定离线可用性的核心在于Service Worker是否成功注册并缓存关键资源（尤其是HTML入口）；文章系统梳理了indexedDB.open()失败的四大主因——非HTTPS环境、缺乏用户交互触发、隐私模式限制及非法数据库命名，并给出可落地的规避策略；同时强调离线数据同步必须依赖状态标记、幂等接口和健壮重试机制，避免丢失、重复或错乱；最后针对地图瓦片等二进制数据的高效存取与安全清理提供了精细化实践指南，帮助开发者构建真正可靠、可维护的离线Web应用。

IndexedDB 本身不构成“离线存储”，它只是本地数据库；关网后页面白屏，90% 的原因是 Service Worker 没注册成功或没缓存 HTML，而不是 IndexedDB 写错了。

indexedDB.open() 关网就报错？先查这四件事

错误信息如 Failed to execute 'open' on 'indexedDB': access is denied 或静默失败，基本与网络连通性无关，而是浏览器策略拦截：

• 页面未通过 HTTPS（或非 localhost）加载 —— Safari 和新版 Chrome 直接拒开数据库
• 调用 indexedDB.open() 时用户尚未触发任何交互（如点击、触摸）—— iOS Safari 要求首次打开必须由用户手势驱动
• 运行在无痕/隐私模式下 —— 数据库是临时的，关闭窗口即丢，且首次写入可能被拒绝
• 数据库名含非法字符（如 /、空格、中文）或版本号不是正整数 —— indexedDB.open("my-app/v2", 2) 会失败，应改为 "my-app-v2"

实操建议：把 indexedDB.open() 移到按钮点击回调里；用 navigator.storage.estimate() 预检配额；对 onblocked 和 onerror 做显式处理，别只等 onsuccess。

Service Worker 不注册，IndexedDB 就是摆设

常见现象：IndexedDB 存了数据、关网刷新页面却白屏或 JS 报错 —— 因为 HTML/CSS/JS 根本没加载进来，indexedDB.open() 压根没机会执行。

• navigator.serviceWorker.register() 必须在页面加载完成后调用，不能放在 defer 脚本里却不 await
• sw.js 必须返回 200 状态码，且响应头不能含 Cache-Control: no-store（Nginx/Apache 默认可能加）
• cache.addAll(["/", "/index.html"]) 是硬性要求 —— 缺少 / 或 /index.html，断网后连 JS 入口都拿不到
• 不要在 fetch 事件中对所有请求 fallback 到 cache；未缓存的 API 应透传或返回 503，否则掩盖真实问题

验证方式：DevTools → Application → Service Workers，看是否显示 “Active”；若为空白或报错，说明注册根本没走通。

离线写入后怎么安全同步到服务器

难点不在“存”，而在“不丢、不重、不乱”。关键靠状态字段 + 幂等接口：

• 每条待同步记录加 syncStatus 字段（值为 "pending"/"synced"/"failed"）和唯一 id
• 同步前查 syncStatus === "pending" 的记录，按时间戳升序逐条 POST；成功后用 put() 更新状态
• 网络失败时捕获 fetch() 的 reject，保留 "failed" 状态，下次联网再重试，别清空队列
• 服务端必须幂等：收到重复 id 请求，应 INSERT ON CONFLICT DO NOTHING 或类似逻辑

注意：同步逻辑不能塞进 online 事件回调里直接发请求 —— 该事件可能在页面未完全激活时触发，导致 fetch 失败。建议加一个轻量轮询或用 setTimeout 延迟几秒再启动同步流程。

存地图瓦片这类二进制数据，别用 Blob 直接塞

存 PNG/JPEG 瓦片时，Blob 不是最佳选择；ArrayBuffer + 显式 mimeType 字段更可控：

• 对象仓库结构推荐：{ id: "12/2048/1365", data: ArrayBuffer, mimeType: "image/png", timestamp: Date.now() }
• 主键用 id（即 z/x/y 字符串），避免嵌套或冗余索引；如需按缩放级别清理，可额外建 zoomIndex（keyPath: z）
• 批量写入控制在每次事务 50–200 条，防阻塞和配额超限；用 Promise.all() 或递归确保顺序完成
• 读取时用 URL.createObjectURL(new Blob([arrayBuffer], {type: mimeType})) 生成 src，注意设置 crossOrigin="anonymous"，否则 Canvas 绘图可能污染失效

真正容易被忽略的是清理机制：用户多次下载不同区域包，packageId 字段和多条件游标遍历删除（index.openCursor(IDBKeyRange.only(packageId))）比直接 deleteDatabase() 更安全、更可控。

以上就是《HTML IndexedDB离线存储教程》的详细内容，更多关于的资料请关注golang学习网公众号！