使用 IndexedDB 构建离线优先的 Web 应用

在移动互联网和弱网环境依然普遍存在的今天，用户对 Web 应用的期待早已不再是“必须有网才能用”。无论是地铁里查看待办清单，还是飞机上继续编辑文档，离线优先（Offline-First）的设计理念正在成为现代 Web 应用的重要标准。而在浏览器提供的诸多存储方案中，IndexedDB 凭借其强大的容量、异步能力和结构化查询特性，成为构建离线优先应用的核心基石。

为什么离线优先需要 IndexedDB

传统的 Web 存储方案各有局限。Cookie 容量仅有 4KB 左右，且会随每次 HTTP 请求发送到服务器；localStorage 虽然简单易用，但容量通常限制在 5MB，且是同步 API，大量读写会阻塞主线程；SessionStorage 更是随会话结束而清空。这些方案都无法承载离线应用所需的复杂数据结构和可观的数据量。

IndexedDB 则完全不同。它是一个运行在浏览器中的事务型 NoSQL 数据库，具备以下关键优势：

• 大容量存储：通常可占用磁盘空间的 50% 甚至更多，足以缓存大量业务数据。
• 异步 API：所有操作都不会阻塞 UI 线程，保证应用流畅。
• 索引与查询：支持创建索引，可以高效地按条件检索数据，而不仅仅是键值对。
• 事务支持：保证数据操作的原子性和一致性，避免部分写入导致的数据损坏。
• 存储结构化数据：可以直接存储对象、数组、Blob、File 等 JavaScript 原生类型，无需手动序列化。

这些特性使 IndexedDB 成为离线优先架构中本地数据持久化的首选。

IndexedDB 核心概念速览

在动手编码前，有必要理解几个核心概念：

• 数据库（Database）：一个应用可以创建多个数据库，每个数据库有名称和版本号。
• 对象仓库（Object Store）：类似于关系型数据库中的表，用于存放数据记录。
• 索引（Index）：基于对象仓库中某个属性建立的快速查找结构。
• 事务（Transaction）：一组数据库操作的集合，要么全部成功，要么全部失败。
• 游标（Cursor）：用于遍历对象仓库或索引中的多条记录。

IndexedDB 的 API 基于事件回调，虽然略显繁琐，但现代浏览器已支持 Promise 化封装，也有 idb、Dexie.js 等优秀库可以大幅简化开发。

构建离线优先应用的基本步骤

1. 打开或创建数据库

使用 indexedDB.open() 打开数据库，并在 onupgradeneeded 事件中定义对象仓库和索引。版本号变化时会触发升级逻辑，这是修改数据库结构的唯一时机。

const request = indexedDB.open('MyOfflineApp', 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  if (!db.objectStoreNames.contains('notes')) {
    const store = db.createObjectStore('notes', { keyPath: 'id', autoIncrement: true });
    store.createIndex('updatedAt', 'updatedAt', { unique: false });
  }
};

2. 封装数据访问层

直接使用原生 API 会让代码充满回调嵌套。建议封装一个轻量的数据访问层，统一处理增删改查。例如使用 idb 库：

import { openDB } from 'idb';

const dbPromise = openDB('MyOfflineApp', 1, {
  upgrade(db) {
    const store = db.createObjectStore('notes', { keyPath: 'id', autoIncrement: true });
    store.createIndex('updatedAt', 'updatedAt');
  },
});

export async function addNote(note) {
  const db = await dbPromise;
  return db.add('notes', note);
}

export async function getAllNotes() {
  const db = await dbPromise;
  return db.getAllFromIndex('notes', 'updatedAt');
}

3. 实现离线读写与同步队列

离线优先应用的核心逻辑是：所有写操作先写入本地 IndexedDB，再尝试同步到服务器。如果网络不可用，则将待同步操作放入一个“同步队列”对象仓库，等网络恢复后再依次提交。

典型流程如下：

1. 用户创建或修改数据。
2. 立即写入 IndexedDB 中的业务仓库，同时向同步队列添加一条操作记录。
3. 如果 navigator.onLine 为 true，则触发同步；否则监听 online 事件，待恢复后同步。
4. 同步成功后，从队列中移除对应记录；失败则保留，可设置重试次数。

4. 利用 Service Worker 缓存静态资源

IndexedDB 负责结构化业务数据，而 Service Worker 的 Cache Storage 则负责缓存 HTML、CSS、JS 和图片等静态资源。两者配合，才能实现完整的离线体验。Service Worker 拦截网络请求，优先返回缓存内容，再后台更新。

5. 处理冲突与版本管理

当本地数据与服务器数据发生冲突时，需要制定合并策略。常见方案包括：

• 最后写入胜出：简单但可能丢失数据。
• 版本向量或时间戳：为每条记录维护版本号，冲突时提示用户选择。
• 操作转换（OT）或 CRDT：适用于协同编辑场景，但实现复杂。

对于大多数应用，基于时间戳的乐观并发控制已经足够。

实践中的注意事项

• 存储配额与清理：浏览器可能在磁盘紧张时清除 IndexedDB 数据。应使用 navigator.storage.persist() 申请持久化存储权限，并设计数据重建机制。
• 隐私模式：部分浏览器的隐私模式下 IndexedDB 不可用或受限，需要降级处理。
• 错误处理：事务可能因配额超限、版本冲突等原因失败，必须捕获并友好提示用户。
• 性能优化：批量读写时使用单个事务，避免频繁打开数据库连接；合理使用索引，但不要过度索引以免写入变慢。

总结

IndexedDB 为 Web 应用提供了接近原生应用的本地数据存储能力，是构建离线优先体验不可或缺的一环。通过合理的架构设计——本地优先写入、同步队列、Service Worker 缓存以及冲突处理策略——开发者可以打造出在网络不稳定甚至完全离线时依然可用的高质量 Web 应用。随着 PWA 生态的成熟，掌握 IndexedDB 已经从前端开发的加分项变为必备技能。现在就开始，让你的应用在任何网络环境下都能从容应对。

未经允许不得转载：任鹏个人博客 » 使用 IndexedDB 构建离线优先的 Web 应用