IndexedDB 详解：构建真正强大的离线 Web 应用（2025–2026 实用指南）

IndexedDB 是浏览器内置的 NoSQL 数据库，专门为前端设计，用于在客户端存储大量结构化数据，是目前实现离线优先（Offline First）、PWA、复杂前端状态持久化的最强工具。

一、为什么前端需要 IndexedDB？（对比其他存储方式）

一句话结论：
当你的应用需要存储结构化数据（列表、树形、用户生成内容）、支持事务、需要查询/索引、容量要大、必须离线可用时 → IndexedDB 是目前唯一靠谱的选择。

二、核心概念速查表（必须记住的 8 个）

三、2025–2026 推荐的现代写法（Promise + async/await）

// 1. 打开/创建数据库（推荐封装成一个函数）
async function openDB(dbName = 'MyAppDB', version = 1) {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(dbName, version);

    request.onerror = () => reject(request.error);
    request.onsuccess = () => resolve(request.result);

    // 第一次创建或版本升级时触发
    request.onupgradeneeded = (event) => {
      const db = event.target.result;

      // 创建对象存储（类似建表）
      if (!db.objectStoreNames.contains('users')) {
        const store = db.createObjectStore('users', { keyPath: 'id', autoIncrement: true });
        
        // 创建索引（加速查询）
        store.createIndex('email', 'email', { unique: true });
        store.createIndex('age', 'age');
        store.createIndex('createdAt', 'createdAt');
      }

      // 可以创建多个 store
      if (!db.objectStoreNames.contains('todos')) {
        db.createObjectStore('todos', { keyPath: 'id', autoIncrement: true });
      }
    };
  });
}

// 2. 添加数据（事务写操作）
async function addUser(db, user) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('users', 'readwrite');
    const store = tx.objectStore('users');
    const req = store.add(user);

    req.onsuccess = () => resolve(req.result); // 返回自增 id
    req.onerror = () => reject(req.error);
    
    tx.oncomplete = () => console.log('添加成功');
    tx.onerror = () => console.error('事务失败');
  });
}

// 3. 查询（通过主键）
async function getUser(db, id) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('users', 'readonly');
    const store = tx.objectStore('users');
    const req = store.get(id);

    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

// 4. 通过索引查询（推荐写法）
async function findUsersByAge(db, minAge, maxAge) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('users', 'readonly');
    const store = tx.objectStore('users');
    const index = store.index('age');

    const range = IDBKeyRange.bound(minAge, maxAge);
    const request = index.getAll(range);

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

// 5. 使用示例（现代 async/await 风格）
async function main() {
  try {
    const db = await openDB('MyAppDB', 1);

    // 添加
    await addUser(db, {
      name: '重阳',
      email: 'chongyang@example.com',
      age: 28,
      createdAt: new Date()
    });

    // 查询单个
    const user = await getUser(db, 1);
    console.log('找到用户：', user);

    // 范围查询
    const adults = await findUsersByAge(db, 18, 40);
    console.log('18-40岁用户：', adults);

  } catch (err) {
    console.error('IndexedDB 操作失败：', err);
  }
}

main();

四、2025–2026 真实场景最佳实践

五、常见坑 & 解决方案（2026 年视角）

1. Safari 兼容性最差
   → 尽量避免使用 autoIncrement + 复杂索引
   → 测试时必须用真实 iOS 设备/Safari

2. 事务只能执行一次请求
   → 错误做法：一个事务里多次 get/put
   → 正确：批量操作用 cursor 或 getAll

3. 数据库被其他标签页锁定
   → 总是用 try-catch + 版本升级策略

4. 数据量大时性能急剧下降
   → 必须建索引
   → 使用游标 + limit 分页
   → 不要一次性 getAll 几万条

5. 删除/清空数据库

   indexedDB.deleteDatabase('MyAppDB');
   

一句话总结给前端开发者：

如果你的 Web 应用需要离线可用、存储几十 MB 以上结构化数据、支持复杂查询，
那么 IndexedDB + Promise + async/await + 封装好的 DB 类 是目前最强大、最可靠的客户端存储方案。

你现在最想深入哪个方向？

• 封装一个现代的 IndexedDB wrapper 类（推荐写法）
• IndexedDB + Service Worker 完整离线同步方案
• 复合索引 & 游标分页实战代码
• PWA 中 IndexedDB 与 localForage 的对比选择
• 如何优雅处理版本升级与数据迁移

告诉我，我可以继续展开～