IndexedDB游标遍历技巧详解

IndexedDB 的游标（cursor）并非普通可迭代对象，而是一个异步、状态敏感的“数据指针”，必须在 onsuccess 回调中通过 continue() 或 advance() 主动推进，并显式检查 cursor 是否为 null 来终止遍历——任何试图用 for...of、forEach 或跨事件循环复用 cursor 的做法都会导致 TypeError 或 InvalidStateError；它既支撑全量遍历与索引范围查询（需配合 IDBKeyRange 精准筛选），也能通过 Promise 封装实现 async/await 风格的线性控制，但背后潜藏着事务超时、并发写入冲突、浏览器兼容性差异等真实生产陷阱，稍有不慎就会让看似简单的遍历逻辑在 Safari 崩溃、在多标签页下静默失败。

IndexedDB 中 cursor 是什么，为什么不能直接用 for 循环遍历

游标（cursor）不是数组或可迭代对象，而是 IndexedDB 异步查询返回的一个“指针”，指向当前匹配的记录。它本身不包含全部数据，只提供 value、key、primaryKey 和移动方法（如 continue()、advance(n)）。直接写 for (let item of cursor) 会报错，因为 cursor 没有 [Symbol.iterator]。

常见错误现象：TypeError: cursor is not iterable 或 undefined is not a function（误调 cursor.forEach）。

• cursor 只能在 onsuccess 回调或 await cursor.advance(1) 后继续使用，不可跨事件循环保存引用
• 每次调用 cursor.continue() 都会触发一次新的 onsuccess，必须在该回调里再次检查 event.target.result 是否为 null（表示遍历结束）
• 若在游标打开期间修改了对应 objectStore 的数据结构（如删字段），后续 cursor.value 可能缺失属性，但不会报错

用 openCursor() 遍历所有记录（最常用场景）

这是读取整个 objectStore 的标准方式，适用于分页加载、全量导出、批量更新等。

关键点：必须在 onsuccess 里判断 cursor 是否存在，再处理值 + 主动推进。

const transaction = db.transaction('users', 'readonly');
const store = transaction.objectStore('users');
const request = store.openCursor();

request.onsuccess = function(event) {
  const cursor = event.target.result;
  if (!cursor) return; // 游标到底，结束

  console.log(cursor.value.name); // 访问当前记录
  cursor.continue(); // 推进到下一条
};

• 不要在 onsuccess 外调用 cursor.continue()，否则报 InvalidStateError
• 如果想限制遍历数量，改用 cursor.advance(10) 替代 continue()，它跳过接下来 9 条，只取第 10 条
• 注意事务生命周期：若遍历耗时长，事务可能自动关闭（尤其在 Safari 中），建议加 transaction.oncomplete 做收尾

用 index.openCursor() 按索引范围遍历（带条件筛选）

当需要查 “status = 'active'” 或 “createdAt > 2023-01-01” 这类条件时，必须先建索引，再用 index.openCursor()，不能靠 JS 过滤全部数据。

示例：查 status 索引中所有 'active' 记录

const index = store.index('status');
const range = IDBKeyRange.only('active');
const request = index.openCursor(range);

request.onsuccess = function(event) {
  const cursor = event.target.result;
  if (!cursor) return;

  console.log(cursor.value); // 注意：这里 cursor.value 是完整 record，不是索引值
  cursor.continue();
};

• IDBKeyRange.lowerBound() / upperBound() 支持开闭区间，例如 IDBKeyRange.lowerBound(100, true) 表示 > 100
• 如果索引是多字段（如 store.createIndex('byStatusAndAge', ['status', 'age'])），range 必须按字段顺序传数组，如 IDBKeyRange.bound(['active', 18], ['active', 65])
• 未命中任何记录时，cursor 仍为 null，不会触发 error，这点和 get() 不同

用 async/await 封装游标遍历（避免回调地狱）

原生 IndexedDB 是纯事件驱动，但可以用 Promise 包一层，让逻辑更线性。注意：不能 await 整个游标，只能 await 每次 continue() 的结果。

function iterateCursor(cursor) {
  return new Promise((resolve) => {
    cursor.onsuccess = () => {
      resolve(cursor.result);
    };
  });
}

// 使用示例（在 transaction 内）
let cursor = await store.openCursor();
while (cursor) {
  console.log(cursor.value);
  cursor = await iterateCursor(cursor.continue());
}

• 每次 cursor.continue() 返回的是新请求（IDBRequest），不是新游标，所以要 await 它的 success 结果才能拿到下一个 cursor
• 这个模式容易忽略事务超时，建议搭配 transaction.abort() 防止卡死，或改用 getAll()（仅适用于小数据量）
• Chrome 120+ 支持 cursor.next()（返回 Promise），但目前 Safari 和 Firefox 尚未实现，生产环境慎用

游标真正的复杂点不在语法，而在它和事务、版本升级、并发写入的耦合——比如遍历时另一个 tab 正在删库，你的 cursor.continue() 可能突然失败且无明确错误码。这种边界情况，文档很少提，但线上真会出。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《IndexedDB游标遍历技巧详解》文章吧，也可关注golang学习网公众号了解相关技术文章。