IndexedDB 实战指南：告别回调地狱，用现代方案掌控浏览器数据库

IndexedDB 是浏览器提供的唯一一个支持大容量结构化数据存储的客户端数据库——单个源可存储数百 MB 数据，支持索引、事务和游标遍历，是 PWA 离线应用和复杂前端状态持久化的基石。然而，原生 IndexedDB API 的设计停留在 2015 年的回调时代，代码冗长、错误处理困难、版本迁移极易出错，导致大量开发者宁可用 LocalStorage 存 JSON 也不愿碰它。本文将用 idb 和 Dexie.js 两个现代封装库，带你从「痛苦的原始 API」走向「优雅的生产实践」，覆盖离线优先架构、数据同步策略、性能调优和常见踩坑。

📌 记住： IndexedDB 不是 LocalStorage 的升级版。它是异步的、支持事务的、可存储结构化数据（包括 Blob、File、ArrayBuffer）的完整数据库。如果你的应用需要存储超过 5MB 的客户端数据，或者需要复杂的查询能力，IndexedDB 是唯一的选择。

🔧 一、原生 API 的痛苦与现代替代方案

1.1 原生 IndexedDB API：为什么大家都想逃离

先看一段「正常」的原生 IndexedDB 代码——打开数据库、创建对象存储、添加一条记录：

// ❌ 原生 IndexedDB：回调地狱的经典示例
function addUser(user) {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open('MyApp', 2);
    
    request.onerror = () => reject(request.error);
    
    request.onupgradeneeded = (event) => {
      const db = event.target.result;
      if (!db.objectStoreNames.contains('users')) {
        const store = db.createObjectStore('users', { keyPath: 'id' });
        store.createIndex('email', 'email', { unique: true });
        store.createIndex('name', 'name', { unique: false });
      }
    };
    
    request.onsuccess = (event) => {
      const db = event.target.result;
      const tx = db.transaction('users', 'readwrite');
      const store = tx.objectStore('users');
      const addReq = store.add(user);
      
      addReq.onsuccess = () => resolve(addReq.result);
      addReq.onerror = () => reject(addReq.error);
      tx.onerror = () => reject(tx.error);
    };
  });
}

这段代码做了什么？只是往数据库里添加一条记录，却需要 4 层嵌套、手动管理 Promise、分别处理 request 和 transaction 的错误。在实际项目中，一个简单的 CRUD 操作动辄 50-80 行代码，而且极其容易遗漏错误处理。

⚠️ 警告： 原生 IndexedDB 的 onupgradeneeded 回调是唯一能修改数据库 schema 的地方。如果你在这里犯错（比如忘记处理旧版本升级），用户的数据库会永久损坏，只能清除站点数据才能恢复。

1.2 两个现代封装库对比

目前社区最成熟的两个 IndexedDB 封装库是 idb 和 Dexie.js。它们的设计理念完全不同，适用场景也不同：

💡 提示： 如果你只需要简单的键值存储或缓存，用 idb；如果你需要复杂查询、索引、实时订阅，用 Dexie.js。不要为了 1.2KB 的包体积节省而把项目写成回调地狱。

🚀 二、实战：用 Dexie.js 构建离线优先应用

2.1 数据库定义与类型安全

Dexie.js 最大的优势之一是 schema 定义极其简洁，而且天然支持 TypeScript 泛型：

// database.ts — 定义数据库 schema
import Dexie, { type EntityTable } from 'dexie';

// 定义数据模型接口
interface User {
  id: number;
  name: string;
  email: string;
  avatar?: string;
  createdAt: Date;
  syncStatus: 'pending' | 'synced' | 'conflict';
}

interface Task {
  id: number;
  userId: number;
  title: string;
  completed: boolean;
  priority: 'low' | 'medium' | 'high';
  dueDate?: Date;
  updatedAt: Date;
  syncStatus: 'pending' | 'synced' | 'conflict';
}

// 定义数据库，注入类型
class AppDatabase extends Dexie {
  users!: EntityTable<User, 'id'>;
  tasks!: EntityTable<Task, 'id'>;

  constructor() {
    super('MyAppDB');
    
    // 版本 1：初始 schema
    this.version(1).stores({
      users: '++id, &email, name, createdAt',
      tasks: '++id, userId, completed, priority, dueDate, updatedAt'
    });

    // 版本 2：新增 syncStatus 索引
    this.version(2).stores({
      users: '++id, &email, name, createdAt, syncStatus',
      tasks: '++id, userId, completed, priority, dueDate, updatedAt, syncStatus'
    });
  }
}

export const db = new AppDatabase();

Dexie.js 的 schema 语法非常直观：++id 表示自增主键，&email 表示唯一索引，name 表示普通索引。多个索引用逗号分隔。版本升级时，Dexie 会自动处理数据迁移——你只需要在新版本中声明新的 schema，它会保留旧数据并添加新索引。

📌 记住： Dexie.js 的 version() 是累加的。每个版本只需要声明与上一版本的差异，不要在每个版本中重复写全部 schema。

2.2 CRUD 操作与高级查询

Dexie.js 的查询语法类似 SQL，链式调用非常直观：

// operations.ts — 完整的 CRUD 操作示例
import { db } from './database';

// ========== 创建 ==========
// 添加单条记录
await db.users.add({
  name: '张三',
  email: 'zhangsan@example.com',
  createdAt: new Date(),
  syncStatus: 'pending'
});

// 批量添加（性能远优于逐条 add）
await db.tasks.bulkAdd([
  { userId: 1, title: '完成项目设计', completed: false, priority: 'high', updatedAt: new Date(), syncStatus: 'pending' },
  { userId: 1, title: '编写单元测试', completed: false, priority: 'medium', updatedAt: new Date(), syncStatus: 'pending' },
  { userId: 1, title: '部署到生产环境', completed: false, priority: 'high', updatedAt: new Date(), syncStatus: 'pending' }
]);

// ========== 查询 ==========
// 按索引查询
const highPriorityTasks = await db.tasks
  .where('priority').equals('high')
  .and(task => !task.completed)
  .sortBy('dueDate');

// 复合条件查询
const recentPendingTasks = await db.tasks
  .where('updatedAt').above(new Date(Date.now() - 7 * 24 * 60 * 60 * 1000))
  .and(task => task.syncStatus === 'pending')
  .toArray();

// 全文搜索（利用 filter，注意性能）
const searchResults = await db.tasks
  .filter(task => task.title.includes('项目'))
  .toArray();

// 分页查询
const pageSize = 20;
const page = 2;
const paginatedTasks = await db.tasks
  .orderBy('updatedAt')
  .reverse()
  .offset((page - 1) * pageSize)
  .limit(pageSize)
  .toArray();

// ========== 更新 ==========
// 按主键更新
await db.tasks.update(1, { completed: true, updatedAt: new Date() });

// 按条件批量更新
await db.tasks
  .where('priority').equals('high')
  .modify({ syncStatus: 'pending' });

// ========== 删除 ==========
// 按主键删除
await db.tasks.delete(1);

// 按条件批量删除
await db.tasks
  .where('completed').equals(true)
  .and(task => task.updatedAt < new Date(Date.now() - 30 * 24 * 60 * 60 * 1000))
  .delete();

💡 提示： bulkAdd 和 bulkPut 的性能远优于在循环中逐条调用 add/put。在批量导入 10,000 条记录时，bulkAdd 比逐条 add 快 20-50 倍，因为它在单个事务中完成所有操作。

2.3 响应式查询：liveQuery

Dexie.js 的杀手级特性是 liveQuery——它能让查询结果自动响应数据变化，无需手动轮询或设置监听器：

// live-query.ts — 响应式查询，自动更新 UI
import { liveQuery } from 'dexie';
import { db } from './database';

// 方法 1：配合 RxJS 使用
import { from } from 'rxjs';

const pendingTasks$ = from(
  liveQuery(() =>
    db.tasks
      .where('syncStatus').equals('pending')
      .toArray()
  )
);

// 方法 2：配合 React 使用（自定义 Hook）
import { useLiveQuery } from 'dexie-react-hooks';

function TaskList({ userId }: { userId: number }) {
  // 当 tasks 表中 userId 对应的数据变化时，自动重新查询
  const tasks = useLiveQuery(
    () => db.tasks.where('userId').equals(userId).toArray(),
    [userId]
  );

  if (!tasks) return <div>加载中...</div>;

  return (
    <ul>
      {tasks.map(task => (
        <li key={task.id} style={{ textDecoration: task.completed ? 'line-through' : 'none' }}>
          {task.title} [{task.priority}]
        </li>
      ))}
    </ul>
  );
}

// 方法 3：配合 Vue 使用
import { ref } from 'vue';

const tasks = ref<Task[]>([]);

// 自动追踪依赖，数据变化时重新执行
const observable = liveQuery(() =>
  db.tasks.where('completed').equals(false).toArray()
);

const subscription = observable.subscribe({
  next: (result) => { tasks.value = result; },
  error: (err) => { console.error('查询失败:', err); }
});

// 组件卸载时取消订阅
// onUnmounted(() => subscription.unsubscribe());

liveQuery 的原理是：它会自动追踪你在回调函数中访问了哪些表和索引，然后在这些表发生变化时重新执行查询。这比手动监听 MutationObserver 或轮询数据库要优雅得多。

⚠️ 警告： liveQuery 会在每次数据变化时重新执行整个查询。如果你的查询很复杂（比如涉及大量 filter），频繁的写操作可能导致性能问题。在这种情况下，考虑使用 debounce 或手动控制刷新频率。

💡 三、生产环境的坑点与最佳实践

3.1 事务（Transaction）的隐式提交陷阱

IndexedDB 的事务是「自动提交」的——当所有请求完成后，如果没有新的异步操作排队，事务会在当前微任务结束后自动提交。这是开发者踩坑最多的地方：

// ❌ 错误：事务在 await 后被隐式提交
async function brokenTransfer(fromId: number, toId: number, amount: number) {
  const from = await db.accounts.get(fromId);
  // ↑ 第一个 await 后，事务已提交！
  const to = await db.accounts.get(toId);
  // ↑ 这里已经不在事务中了，两个操作不在同一个事务里
  
  await db.accounts.update(fromId, { balance: from!.balance - amount });
  await db.accounts.update(toId, { balance: to!.balance + amount });
  // ↑ 如果中间出错，只有扣款没有入账，数据不一致！
}

// ✅ 正确：在同一个事务中完成所有操作
async function correctTransfer(fromId: number, toId: number, amount: number) {
  await db.transaction('rw', db.accounts, async (tx) => {
    const from = await tx.table('accounts').get(fromId);
    const to = await tx.table('accounts').get(toId);
    
    if (!from || !to) throw new Error('账户不存在');
    if (from.balance < amount) throw new Error('余额不足');
    
    await tx.table('accounts').update(fromId, { balance: from.balance - amount });
    await tx.table('accounts').update(toId, { balance: to.balance + amount });
  });
}

Dexie.js 的 db.transaction('rw', ...) 会自动将事务对象传递给回调函数，确保所有操作在同一个事务中。但即使使用 Dexie，你仍然需要注意：不要在事务回调中使用外部的 db 引用，要使用回调参数 tx。

3.2 存储配额与持久化策略

浏览器对 IndexedDB 的存储配额是有上限的，而且不同浏览器的策略完全不同：

⚠️ 警告： Safari 的 ITP（Intelligent Tracking Prevention）会在 7 天未访问后清除网站的 IndexedDB 数据！这意味着如果你的 PWA 用户超过 7 天没打开应用，所有离线数据都会丢失。解决方案是请求持久化存储。

// storage.ts — 请求持久化存储并检查配额
async function requestPersistentStorage(): Promise<boolean> {
  // 检查浏览器是否支持持久化存储
  if (!navigator.storage || !navigator.storage.persist) {
    console.warn('浏览器不支持持久化存储 API');
    return false;
  }

  // 检查是否已经持久化
  const isPersisted = await navigator.storage.persisted();
  if (isPersisted) {
    console.log('✅ 存储已持久化');
    return true;
  }

  // 请求持久化（Chrome 会弹出权限提示）
  const result = await navigator.storage.persist();
  if (result) {
    console.log('✅ 持久化存储已授权');
  } else {
    console.warn('❌ 持久化存储被拒绝，数据可能被浏览器自动清除');
  }
  return result;
}

async function checkStorageQuota() {
  if (!navigator.storage || !navigator.storage.estimate) return;
  
  const { usage, quota } = await navigator.storage.estimate();
  if (!usage || !quota) return;

  const usageMB = (usage / 1024 / 1024).toFixed(2);
  const quotaMB = (quota / 1024 / 1024).toFixed(2);
  const percentage = ((usage / quota) * 100).toFixed(1);

  console.log(`存储使用: ${usageMB} MB / ${quotaMB} MB (${percentage}%)`);
  
  // 超过 80% 时发出警告
  if (usage / quota > 0.8) {
    console.warn('⚠️ 存储即将满，请清理旧数据！');
    return { warning: true, usageMB, quotaMB, percentage };
  }
  return { warning: false, usageMB, quotaMB, percentage };
}

3.3 离线数据同步策略

离线应用最核心的问题不是「如何存储数据」，而是「如何在恢复网络后同步数据」。以下是一个实用的同步策略实现：

// sync.ts — 带冲突检测的离线同步方案
import { db } from './database';

interface SyncResult {
  pushed: number;
  pulled: number;
  conflicts: number;
}

// 推送本地待同步数据到服务器
async function pushPendingChanges(): Promise<{ pushed: number; conflicts: number }> {
  const pendingTasks = await db.tasks
    .where('syncStatus').equals('pending')
    .toArray();

  let pushed = 0;
  let conflicts = 0;

  for (const task of pendingTasks) {
    try {
      const response = await fetch('/api/tasks', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          id: task.id,
          title: task.title,
          completed: task.completed,
          priority: task.priority,
          updatedAt: task.updatedAt.toISOString()
        })
      });

      if (response.status === 409) {
        // 冲突：服务器端数据更新
        const serverTask = await response.json();
        await db.tasks.update(task.id, {
          ...serverTask,
          updatedAt: new Date(serverTask.updatedAt),
          syncStatus: 'conflict'
        });
        conflicts++;
      } else if (response.ok) {
        await db.tasks.update(task.id, { syncStatus: 'synced' });
        pushed++;
      }
    } catch (error) {
      // 网络错误，保持 pending 状态，下次重试
      console.warn(`推送任务 ${task.id} 失败:`, error);
    }
  }

  return { pushed, conflicts };
}

// 从服务器拉取最新数据
async function pullLatestChanges(): Promise<{ pulled: number }> {
  // 获取最后一次同步时间
  const syncMeta = await db.meta.get('lastSyncTime');
  const since = syncMeta?.value || new Date(0).toISOString();

  const response = await fetch(`/api/tasks?since=${encodeURIComponent(since)}`);
  const serverTasks = await response.json();

  let pulled = 0;

  for (const serverTask of serverTasks) {
    const localTask = await db.tasks.get(serverTask.id);

    if (!localTask) {
      // 新记录，直接插入
      await db.tasks.add({
        ...serverTask,
        updatedAt: new Date(serverTask.updatedAt),
        syncStatus: 'synced'
      });
      pulled++;
    } else if (localTask.syncStatus === 'synced') {
      // 本地未修改，直接覆盖
      await db.tasks.update(serverTask.id, {
        title: serverTask.title,
        completed: serverTask.completed,
        priority: serverTask.priority,
        updatedAt: new Date(serverTask.updatedAt),
        syncStatus: 'synced'
      });
      pulled++;
    }
    // 如果本地是 pending 或 conflict，不覆盖，留给冲突解决
  }

  // 更新同步时间
  await db.meta.put({ key: 'lastSyncTime', value: new Date().toISOString() });

  return { pulled };
}

// 完整同步流程
async function sync(): Promise<SyncResult> {
  const { pushed, conflicts } = await pushPendingChanges();
  const { pulled } = await pullLatestChanges();
  
  console.log(`同步完成: 推送 ${pushed} 条, 拉取 ${pulled} 条, 冲突 ${conflicts} 条`);
  return { pushed, pulled, conflicts };
}

// 网络恢复时自动同步
window.addEventListener('online', () => {
  console.log('🌐 网络恢复，开始同步...');
  sync().catch(console.error);
});

// 定期同步（每 5 分钟）
setInterval(() => {
  if (navigator.onLine) {
    sync().catch(console.error);
  }
}, 5 * 60 * 1000);

⚡ 关键结论： 离线同步的核心原则是「最终一致性」——不要试图实现实时同步，而是保证数据最终会收敛到一致状态。优先推送本地变更，再拉取服务器变更，冲突时标记而不是自动覆盖。

⚡ 四、性能优化与调试技巧

4.1 批量操作性能对比

以下是我在 Chrome 126 上的实测数据（10,000 条记录，每条 ~500 字节）：

💡 提示： 如果你需要导入超过 10 万条记录，考虑使用 Web Worker 中的 IndexedDB 操作，避免阻塞主线程。Dexie.js 支持在 Worker 中使用。

4.2 调试工具

Chrome DevTools 对 IndexedDB 的支持非常完善：

1. Application 面板 → IndexedDB：查看所有数据库、对象存储、索引和数据
2. Console 中直接查询：在 DevTools 的 Console 中，IndexedDB 对象可以直接访问
3. Storage 面板：查看配额使用情况和持久化状态

// debug.ts — 开发环境下的数据库调试工具
if (import.meta.env.DEV) {
  // 暴露到全局，方便 Console 调试
  (window as any).__db = db;

  // 监听数据库错误
  db.on('error', (error) => {
    console.error('❌ IndexedDB 错误:', error);
  });

  // 监听版本变化（多标签页场景）
  db.on('versionchange', () => {
    console.warn('⚠️ 数据库版本已变化，建议刷新页面');
    db.close();
  });
}

4.3 多标签页数据同步

当用户同时打开多个标签页时，IndexedDB 的 versionchange 事件是唯一能感知其他标签页修改 schema 的机制。但数据层面的同步需要借助 BroadcastChannel：

// multi-tab.ts — 多标签页数据同步
const channel = new BroadcastChannel('db-sync');

// 当当前标签页修改数据时，通知其他标签页
db.on('changes', (changes) => {
  channel.postMessage({
    type: 'data-changed',
    tables: changes.map(c => c.table),
    timestamp: Date.now()
  });
});

// 监听其他标签页的通知
channel.onmessage = (event) => {
  if (event.data.type === 'data-changed') {
    console.log(`📡 其他标签页修改了 ${event.data.tables.join(', ')} 表`);
    // liveQuery 会自动响应变化，这里只需要处理 UI 刷新逻辑
  }
};

// 监听数据库版本变化（其他标签页升级了数据库）
db.on('versionchange', () => {
  alert('应用已更新，正在刷新页面...');
  db.close();
  location.reload();
});

📌 记住： liveQuery 只能监听当前标签页的数据变化。如果你需要跨标签页的实时更新，必须使用 BroadcastChannel 配合 liveQuery。

✅ 总结与最佳实践清单

选择封装库：

• ✅ 简单场景用 idb（~1.2KB），复杂场景用 Dexie.js（~22KB）
• ❌ 不要直接使用原生 IndexedDB API，除非你在写封装库

数据设计：

• ✅ 为所有常用查询路径创建索引
• ✅ 使用 syncStatus 字段标记同步状态
• ❌ 不要在 IndexedDB 中存储需要全文搜索的大量文本（考虑 SQLite FTS）

事务管理：

• ✅ 始终使用 db.transaction('rw', ...) 确保操作原子性
• ❌ 不要在事务回调中使用外部的 db 引用
• ❌ 不要在事务中执行网络请求

存储管理：

• ✅ 应用启动时检查存储配额并请求持久化
• ✅ 定期清理过期数据
• ⚠️ Safari ITP 会清除 7 天未访问的站点数据

相关工具推荐：

• 🔧 idb（~1.2KB）— 轻量级 IndexedDB 封装
• 🔧 Dexie.js（~22KB）— 功能完整的 IndexedDB ORM
• 🔧 localForage — LocalStorage 风格 API + IndexedDB 后端
• 🔧 idb-keyval — 极简键值存储（~600B）
• 🔧 Workbox — PWA 离线缓存策略