IndexedDB事务操作全解析

本文深入剖析了HTML IndexedDB事务的核心机制与常见陷阱，直击开发者最头疼的TransactionInactiveError、数据部分写入、批量操作失败定位难等痛点，揭示事务并非持久连接而是受事件循环严格约束的短暂执行容器；强调所有关联操作必须在同一个事务内完成以保障原子性，详解如何安全分批写入、精准捕获单条失败、正确处理versionchange升级事务，并给出可落地的代码实践模式——帮你避开90%的IndexedDB生产级坑。

为什么 transaction 突然失效、报 TransactionInactiveError

事务不是“打开就一直有效”的连接，而是有明确生命周期的执行容器。一旦当前事件循环结束、且没有待决请求（request.onsuccess 还没触发），事务立刻自动终止——哪怕你刚调用完 objectStore.add()，下一行再调用 put() 就会抛错。

常见错误现象：

• for 循环里连续写入，只成功第一条
• 在 request.onsuccess 外部保存了 objectStore 引用，后续复用时报错
• 异步回调里误以为事务还在，直接操作已失效的对象存储

正确做法：

• 所有操作必须在同一个事务内发起，且不能跨事件循环“续命”
• 批量写入必须用 Promise.all(requests.map(r => new Promise(...))) 或链式回调（在前一个 request.onsuccess 里发下一个）
• 不要缓存 objectStore，每次操作都从 transaction.objectStore('name') 重新取

readwrite 事务为什么没回滚、数据却部分写入了

IndexedDB 的原子性只在单个事务内成立：事务中任意一个请求失败（比如 key 冲突、类型不匹配），整个事务自动 abort，之前成功的操作也全部撤销。

但如果你把多个操作拆到不同事务里，就完全失去原子性保障。例如：

• 先开一个 readwrite 事务删旧数据，再开另一个写新数据 —— 中间出错，旧数据没了，新数据没写成
• 用 await 包裹两个独立 add() 调用，实际是两个事务，无法保证一起成功或失败

务必确保所有关联操作都在同一 transaction 实例中完成：

• 用 db.transaction(['store1', 'store2'], 'readwrite') 显式声明多 store
• 所有 add()、put()、delete() 都基于这个 transaction 发起
• 监听 transaction.oncomplete 和 transaction.onerror 做统一收尾

如何安全地批量插入并捕获具体哪条失败

原生 IndexedDB 不支持“部分成功”，但你可以控制粒度：把一批数据拆成小批次（如每 50 条一个事务），既防阻塞，又便于定位问题。

关键点：

• 每个批次单独开 readwrite 事务，避免单事务过大导致长时间阻塞 UI
• 对每个 IDBRequest 单独绑定 onerror，记录失败的索引和 event.target.error
• 别依赖 transaction.onerror 拿具体错误——它只告诉你“事务崩了”，不说明哪条 request 出的问题
• 示例片段：

  const requests = data.slice(i, i + 50).map((item, idx) => {
    const req = store.add(item, item.id);
    req.onerror = () => console.error(`Item ${i + idx} failed:`, req.error);
    return req;
  });

versionchange 事务能干啥、为啥不能手动触发

versionchange 是唯一能修改数据库结构的事务类型，仅在 onupgradeneeded 回调中由系统自动开启。你不能自己调用 db.transaction(..., 'versionchange')，浏览器会直接拒绝。

它的作用非常明确：

• 创建/删除 objectStore
• 调用 createIndex() 或 deleteIndex()
• 重命名 objectStore（IndexedDB 2.0+）

容易被忽略的细节：

• 只要改结构（哪怕只是加个索引），就必须递增 open() 的版本号，否则 onupgradeneeded 根本不会触发
• 升级事务里不能做数据读写（get()、getAll() 可能失败），只能建模
• 如果用户正在使用旧版本页面，升级事务可能被挂起，直到所有旧连接关闭

好了，本文到此结束，带大家了解了《IndexedDB事务操作全解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！