前阵子做一个离线优先的小工具需要在本地存几千条结构化记录还要支持按日期、按分类过滤查询。第一反应是使用 localStorage写了没几行就发现问题——空间不够用、读取卡顿、查询全靠循环遍历。后来换成 IndexedDB 重新实现数据量涨到上万条依然顺畅整个交互也没卡过主线程。IndexedDB 是浏览器内置的 NoSQL 数据库很多前端开发者对它望而却步主要因为 API 风格和老式回调事件比较劝退但真正用过之后会发现它其实就是个“普通数据库”只是需要换一种建模和调用思路。这篇文章我打算按自己实际动手的顺序来写先讲清楚为什么该用 IndexedDB再拆解它的核心模型然后给一个能直接跑起来改的完整案例最后把我踩过的几个坑单独列一节。适合打算在前端做离线缓存、复杂查询或大数据量本地存储的开发者哪怕对 IndexedDB 零基础跟着案例走一遍也能独立上手。1. localStorage不够用的时候IndexedDB才是干这活的工具1.1 localStorage的三个硬伤先说结论localStorage 不是设计来存“正经数据”的。它的三个硬伤在数据量小的时候看不出来一旦数据量上来每个都致命。第一容量太小。按常见浏览器的实现localStorage 每个域名通常只有 5MB 左右空间。这个数字对保存用户偏好、记住一两个页面状态绰绰有余但想存商品列表、消息记录、离线任务队列5MB 很容易被塞满。第二只能存字符串意味着对象必须先 JSON.stringify 再 JSON.parse来回序列化本身就有开销而且一旦字段结构变化老数据解析失败时整个应用都得做兼容兜底。第三API 是同步的读写会阻塞主线程。几百个 key 倒还好上万条记录做遍历筛选的时候页面会直接卡住移动端尤其明显。当初我在那个工具里先用 localStorage 存流水数据大概存到两千条时每次重新渲染列表都要把全量数据 parse 一遍再做数组过滤明显的白屏感就出来了。这个体验问题不是代码能优化的——存储机制本身决定了它不合适。1.2 IndexedDB补上了哪些短板IndexedDB 补的核心短板可以概括成四个词大容量、结构化、异步、可索引。大容量没有 5MB 这种硬限制实际配额通常取决于浏览器和当前磁盘剩余空间比 localStorage 高两三个数量级。结构化直接存储对象原生支持 Date、Blob、ArrayBuffer、File 等类型不需要自己序列化成字符串。异步所有读写都是异步 API不阻塞 UI 渲染适合在页面正常交互的过程中做数据读写。可索引可以为对象仓库的字段建索引查询时直接走索引定位而不是把整张表捞出来线性过滤。光是这四点IndexedDB 就天然适合离线优先应用、数据量较大的前端缓存、以及需要复杂查询的场景。1.3 选型参考什么时候该用IndexedDB我现在的判断标准很简单场景存储方案用户偏好、简单标志位、一两百个字符串键值localStorage需要跨标签页共享且只读的少量配置localStorage几百条以上的结构化数据、需要按字段筛选排序IndexedDB离线优先应用、本地文件缓存BlobIndexedDB需要事务保证多条写入的一致性必须 IndexedDBlocalStorage 做不到另外说一个反直觉的结论IndexedDB 的 API 虽然不友好但它底层的设计思路并不复杂。真正劝退多数人的是它的回调风格和版本管理机制而不是数据库本身。接下来我会把这套机制一层层拆开拆完之后你会发现它其实和关系型数据库有很多共通之处。2. 建库之前先把数据库、对象仓库和索引这几个概念理顺2.1 图书馆类比数据库、对象仓库和索引各管什么IndexedDB 的层级结构可以想象成一个图书馆数据库database相当于一座图书馆本身没有太多结构就是对象仓库的集合。对象仓库object store相当于书架。关系型数据库里的“表”对应的就是 IndexedDB 里的“对象仓库”一张表里存什么对象类型一个仓库里也就存什么对象类型。索引index相当于图书目录索引它不真正存数据而是指向真实记录的位置。给对象的某个字段建索引后就可以按该字段高效查询和排序。游标cursor相当于一个移动的书签用来逐条遍历满足条件的数据。一个常见误区是把 IndexedDB 跟 localStorage 类比觉得它就是个“更大的 JSON 仓库”。这种误解会导致建模时把所有数据塞进一个对象仓库查询靠 getAll 后内存里过滤性能完全发挥不出来。正确的思路是像数据库一样对待它先规划对象仓库再为高频查询字段建立索引。下面这段代码展示了最基本的建库和建仓库逻辑const request indexedDB.open(taskDB, 1); request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(tasks)) { const store db.createObjectStore(tasks, { keyPath: id, autoIncrement: true }); store.createIndex(tag, tag, { unique: false }); store.createIndex(dueDate, dueDate, { unique: false }); store.createIndex(completed, completed, { unique: false }); } };2.2 主键与索引数据怎么被查得快对象仓库里的每条记录都是“键值对”形式值就是你要存的对象本身。键的指定方式有三种用 keyPath 指定对象里的某个字段作为主键用 autoIncrement 自动生成自增数字或者干脆在 add 时手动传一个外部键。主键的职责主要是唯一标识。而查询效率的开关其实在索引上。索引的本质是“字段值 → 主键”的映射。给 dueDate 建索引之后想查“所有到期日在今天之后的任务”可以直接通过索引拿到候选主键列表再回表取数据整个过程不需要全量扫描。索引的 unique 参数类似数据库中的唯一约束。比如邮箱、手机号这类字段可以设置 unique: true而 tag、status 这类重复度高的字段设置 unique: false。2.3 事务和异步API为什么要绕这一圈IndexedDB 的每个读写操作都发生在事务transaction里。事务保证一组操作要么全部成功、要么全部回滚这是 localStorage 根本不具备的能力。比如批量写入用户操作记录时中间任何一条写入失败前面写进去的数据也不会留下半截状态。在 API 层面IndexedDB 使用事件回调而不是 Promise。你调用 store.add() 时会得到一个 IDBRequest 对象真正的结果通过 request.onsuccess 或 request.onerror 返回。从开发体验上看确实比 fetch 那套繁琐一点但这并不影响实际使用——用一个 Promise 封装函数把回调包起来暴露出去的 API 就会非常顺手。这个封装我们在下一节案例里直接实现。另外要理解版本号的作用。indexedDB.open(dbName, version) 中的 version 不是数据库内容的版本号而是“结构版本号”。你只能在 onupgradeneeded 事件里创建、删除对象仓库、修改索引。如果你改了结构但没有提升版本号onupgradeneeded 就不会触发新结构自然也不会生效。这一点很多人第一次接触时都会踩坑后面会专门讲。3. 完整的任务清单案例数据库搭建与增删改查封装3.1 打开数据库并定义对象仓库先明确这个任务清单的数据结构。每条任务包含 id、title、tag、dueDate、completed 五个字段。我们的诉求是支持按标签过滤、按到期日期排序、按完成状态筛选所以建三个索引分别对应 tag、dueDate、completed。数据库版本号从 1 开始。onupgradeneeded 只在版本号升高时触发所以首次打开就会执行建表逻辑之后再次打开则直接进入 onsuccess。let db; function openDB() { return new Promise((resolve, reject) { const request indexedDB.open(taskDB, 1); request.onupgradeneeded (event) { const database event.target.result; if (!database.objectStoreNames.contains(tasks)) { const store database.createObjectStore(tasks, { keyPath: id, autoIncrement: true }); store.createIndex(tag, tag, { unique: false }); store.createIndex(dueDate, dueDate, { unique: false }); store.createIndex(completed, completed, { unique: false }); } }; request.onsuccess (event) { db event.target.result; resolve(db); }; request.onerror (event) { reject(event.target.error); }; }); }这个 openDB 函数里把 db 句柄缓存到模块级变量避免每次操作都重新打开数据库。在真实项目中建议在应用启动时先调用一次 openDB()等 onsuccess 之后再执行后续业务逻辑。如果项目里存在多个入口并发调用 openDB最好用一个 pending promise 做去重防止产生多个数据库连接。3.2 封装一组Promise风格的增删改查IndexedDB 里任何一个写操作都建议放在事务里读操作默认也会创建隐式事务。封装的核心套路是一致的创建事务 → 获取对象仓库 → 发起请求 → 监听事务的 oncomplete 或请求的 onsuccess 来决定何时 resolve。添加任务function addTask(task) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.add(task); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }注意事务的成功标志是 tx.oncomplete 而不是 store.add 的 onsuccess。因为事务里可能包含多条操作等到所有操作都提交完成、事务正常结束才是整个逻辑真正落库的时刻。更新任务时使用 put它会按主键整体替换记录function updateTask(task) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.put(task); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }需要注意updateTask 是整体覆盖。如果只想改 completed 一个字段得先 get 出整条记录修改字段后再 put 回去。否则原对象里其他字段会被清掉这是个非常隐蔽的数据丢失场景。删除任务function deleteTask(id) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.delete(id); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }读取单条记录function getTask(id) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const request store.get(id); request.onsuccess () resolve(request.result); request.onerror () reject(request.error); }); }3.3 用案例代码串一遍操作流程这些函数拼起来就是一个完整的清单功能。新增一条任务、查询全部任务、更新状态、删除任务核心代码可以这样串async function bootstrap() { await openDB(); await addTask({ title: 阅读文档, tag: 学习, dueDate: 2025-05-20, completed: false }); await addTask({ title: 整理笔记, tag: 学习, dueDate: 2025-05-21, completed: false }); await addTask({ title: 写周报, tag: 工作, dueDate: 2025-05-22, completed: true }); const task await getTask(1); console.log(读取单条:, task); const updated { ...task, completed: true }; await updateTask(updated); await deleteTask(2); }这段代码看着挺直观它把 IndexedDB 的“事务 回调”完全封装在 Promise 里业务层就只剩下普通的 async/await。我强烈建议在项目里先做一层这样的封装再在上层业务中使用否则每一处都要处理 IDBRequest 回调代码会迅速膨胀。4. 场景化查询用游标和索引过滤数据而不是全量读取后再筛选4.1 IDBKeyRange查询区间是怎么表达的刚刚的 getTask 只能按主键精确读取。但实际的清单应用里更多是“按日期范围”“按标签等于某个值”这类条件查询这时就要用 IDBKeyRange 来构造查询区间。IDBKeyRange 提供了几个静态方法// 只取某个值 IDBKeyRange.only(学习); // 大于等于某个值 IDBKeyRange.lowerBound(2025-05-20); // 小于等于某个值且不包含边界 IDBKeyRange.upperBound(2025-05-31, true); // 完整闭区间 IDBKeyRange.bound(2025-05-20, 2025-05-31, false, false);bound 的后两个参数分别表示下界和上界是否排除边界。这个规则看着啰嗦但确实是控制包含关系的唯一方式实际开发中别忘了调整。4.2 对象仓库游标与索引游标查询任务的正确姿势是先取索引再在索引上开游标。写一个“查找到期日落在某个区间的任务”function getTasksByDateRange(start, end) { return new Promise((resolve, reject) { const result []; const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const index store.index(dueDate); const range IDBKeyRange.bound(start, end, true, true); const request index.openCursor(range); request.onsuccess () { const cursor request.result; if (cursor) { result.push(cursor.value); cursor.continue(); } else { resolve(result); } }; request.onerror () reject(request.error); }); }这里最值得注意的地方是我们没有在内存里遍历整个仓库而是通过 dueDate 索引只读取目标日期范围内的记录。数据量到上万条时用 getAll 全量加载再 filter 会有明显的内存和时间开销而索引查询基本是毫秒级。4.3 用游标解决排序和分页索引还有一个隐藏能力排序。由于索引天然按键值排序索引游标默认就是按排序后的顺序输出。比如“按 dueDate 倒序”只需要给 openCursor 传入第二个参数 directionconst request index.openCursor(null, prev);null 表示不限范围prev 表示按索引值从大到小访问。同理还有 next、nextunique、prevunique后两个适用于去重查询。分页也可以靠游标实现思路是跳过前 offset 条再收集 limit 条function getTasksByTagWithPagination(tag, offset, limit) { return new Promise((resolve, reject) { const result []; let skipped 0; let fetched 0; const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const index store.index(tag); const request index.openCursor(IDBKeyRange.only(tag)); request.onsuccess () { const cursor request.result; if (!cursor) { resolve(result); return; } if (skipped offset) { skipped; cursor.continue(); return; } result.push(cursor.value); fetched; if (fetched limit) { resolve(result); } else { cursor.continue(); } }; request.onerror () reject(request.error); }); }这里有个小技巧fetch 到 limit 条足够时直接 resolve函数返回后游标不再继续。readonly 事务自然会结束不必担心残留对象导致内存泄漏。5. 版本升级、事务生命周期说说我踩过的IndexedDB这几个坑5.1 TransactionInactiveError事务的隐形生命周期IndexedDB 最容易坑人的就是事务的自动提交机制。事务并不是你手动调 commit 才结束而是在所有请求完成后一旦控制权交回事件循环事务就可能自动提交。我之前写过一段自以为没问题的代码function brokenBatchAdd(tasks) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); tasks.forEach(async (task) { await fetchSomeData(); // 这里让出事件循环 store.add(task); // 可能抛 TransactionInactiveError }); }在 forEach 的 async 回调里fetchSomeData 会中断执行等网络请求返回时事务可能已经被浏览器自动提交了再往事务里 store.add 就会报 TransactionInactiveError。正确做法是把同一事务内的所有操作尽量同步地放入队列不要在事务处理过程中做 await 操作。如果需要先异步获取数据再写入应该等获取完成后再开启事务或者把 fetch 结果提前聚合成数组在一个事务内连续写入。这个错误信息前几次看到时很懵因为报错位置往往离真正的问题代码很远排查思路要从“事务是否还活跃”入手。5.2 onupgradeneeded只在版本升高时触发数据库结构升级必须走版本号。很多开发者会直接在全局代码里调用indexedDB.open(taskDB, 1);后来想加一个新索引就把代码里的版本号改成 2但直接改数字通常没用因为浏览器是根据当前数据库版本和传入版本号比较的。如果数据库已经是 1你现在传 2会触发升级但如果数据库已经是 2你再传 2什么都不会发生。结构总是比代码的版本演进缓慢这是正常的不代表代码有问题。升级逻辑一定放在 onupgradeneeded 里const request indexedDB.open(taskDB, 2); request.onupgradeneeded (event) { const database event.target.result; const tx event.target.transaction; if (!database.objectStoreNames.contains(projects)) { database.createObjectStore(projects, { keyPath: id }); } const store tx.objectStore(tasks); if (!store.indexNames.contains(priority)) { store.createIndex(priority, priority, { unique: false }); } };另一个容易忽视的点是升级事件里的 transaction 是升级事务在 onupgradeneeded 回调里可以继续拿它访问现有的 store 或新建的 store。但不要在 onupgradeneeded 里直接调用 db.close()升级事务还没结束强行关闭会抛异常。5.3 删除、索引和错误处理中的暗坑先看删除。deleteDatabase 调用之后旧的数据库对象并不会立即失效它得等到所有旧连接关闭后才真正开始删除。数据删除后磁盘空间的释放也是异步的浏览器通常要过一阵子才会回收。所以别用“删完立刻检查磁盘占用”这种方式来验证删除是否成功。再看索引。索引里的值如果为 undefined这条记录不会出现在该索引中。比如任务对象里某个任务没有 dueDate 字段那么按 dueDate 建的索引里就没有它按日期区间查询这个任务也查不到。这不是 bug而是设计如此。如果业务上要求这类记录也能被查询到需要给定一个默认值或者在写入前做字段兜底。最后说错误处理。IndexedDB 的 IDBRequest 有 onsuccess 和 onerror很多人只写了 onsuccess漏了 onerror。问题在于写操作失败时如果没有 onerror 监听你可能根本不知道数据没写进去页面还提示“保存成功”。在封装 Promise 时务必同时监听两个回调并把错误 reject 出去。前端开发里最可怕的数据问题不是报错而是“以为写进去了其实没有”。6. 批量写入、跨标签页同步以及如何把IndexedDB用得更顺手6.1 单事务内完成批量写入批量写入的要点是一个事务里连续执行多条 add 或 put。前面我们说过不要在里面 await 任何其他异步操作。一个事务内连续跑循环写入是安全的但如果数据量极大比如一次性写几万条也有可能导致事务长时间占用资源。稳妥的做法是分批次提交每批几百条批与批之间用 await 留出事件循环时间async function batchAddTasks(tasks) { const BATCH_SIZE 500; for (let i 0; i tasks.length; i BATCH_SIZE) { const batch tasks.slice(i, i BATCH_SIZE); await new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); for (const task of batch) { store.add(task); } tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); } }这种分批次写入既保证了事务的一致性边界又避免了一次事务执行太久导致浏览器限制或卡顿的隐患。6.2 跨标签页同步思路IndexedDB 本身的数据在每个标签页都是能读到的但一个标签页写入后另一个标签页不会自动得知。最轻量的方案是借助 BroadcastChannel 做通知写入完成后 postMessage 一个“数据已更新”的消息其他标签页收到后重新查询并刷新界面。const channel new BroadcastChannel(task-channel); // 写入成功后通知 await addTask(task); channel.postMessage(tasks-updated); // 其他标签页监听 channel.onmessage () { refreshTaskList(); };BroadcastChannel 不支持的环境就用 storage 事件兜底但注意 storage 事件只会在 localStorage 变化时触发IndexedDB 变化不会触发它。所以浏览器支持受限的环境下可以退化为定时轮询或手动监听 visibilitychange在页面重新可见时做一次刷新。6.3 封装思路把回调藏到底层我在项目里的习惯是所有 IndexedDB 操作永远不直接在业务代码里裸写 index.openCursor 这种逻辑而是统一封装成一个数据库模块。封装的核心是两件事第一把 IDBRequest 的 onsuccess/onerror 包装成 Promise第二把事务的 oncomplete/onabort 作为整个操作的完成信号。封装完以后业务侧只需要 import 一个包含 get、put、add、delete、query 的模块就能像操作一个普通异步数据库一样使用它。社区里其实也有不少把 IndexedDB 封装成 Promise 风格的工具库挑一个 star 多、维护积极的直接用也行。但如果想深入理解 IndexedDB 的机制我建议自己先写一遍封装这对后续排查问题帮助很大——出了奇怪报错时至少你知道它发生在请求层还是事务层。最后说一个调试技巧浏览器开发者工具的 Application 面板里有 IndexedDB 的实时查看功能可以展开库、对象仓库、索引看到每条记录的具体值也能手动删除记录。我每次做完数据库模块第一件事就是在这里写入几条测试数据肉眼确认索引是否建立、字段是否正确这比在控制台打日志直观得多。排查版本升级问题时也可以先看这里展示的当前数据库版本和仓库列表能少走不少弯路。 
长河君 · 2026/10/18 3:38:11 · 阅读 1.2k IndexedDB实战：从localStorage瓶颈到离线大数据量存储方案
前阵子做一个离线优先的小工具需要在本地存几千条结构化记录还要支持按日期、按分类过滤查询。第一反应是使用 localStorage写了没几行就发现问题——空间不够用、读取卡顿、查询全靠循环遍历。后来换成 IndexedDB 重新实现数据量涨到上万条依然顺畅整个交互也没卡过主线程。IndexedDB 是浏览器内置的 NoSQL 数据库很多前端开发者对它望而却步主要因为 API 风格和老式回调事件比较劝退但真正用过之后会发现它其实就是个“普通数据库”只是需要换一种建模和调用思路。这篇文章我打算按自己实际动手的顺序来写先讲清楚为什么该用 IndexedDB再拆解它的核心模型然后给一个能直接跑起来改的完整案例最后把我踩过的几个坑单独列一节。适合打算在前端做离线缓存、复杂查询或大数据量本地存储的开发者哪怕对 IndexedDB 零基础跟着案例走一遍也能独立上手。1. localStorage不够用的时候IndexedDB才是干这活的工具1.1 localStorage的三个硬伤先说结论localStorage 不是设计来存“正经数据”的。它的三个硬伤在数据量小的时候看不出来一旦数据量上来每个都致命。第一容量太小。按常见浏览器的实现localStorage 每个域名通常只有 5MB 左右空间。这个数字对保存用户偏好、记住一两个页面状态绰绰有余但想存商品列表、消息记录、离线任务队列5MB 很容易被塞满。第二只能存字符串意味着对象必须先 JSON.stringify 再 JSON.parse来回序列化本身就有开销而且一旦字段结构变化老数据解析失败时整个应用都得做兼容兜底。第三API 是同步的读写会阻塞主线程。几百个 key 倒还好上万条记录做遍历筛选的时候页面会直接卡住移动端尤其明显。当初我在那个工具里先用 localStorage 存流水数据大概存到两千条时每次重新渲染列表都要把全量数据 parse 一遍再做数组过滤明显的白屏感就出来了。这个体验问题不是代码能优化的——存储机制本身决定了它不合适。1.2 IndexedDB补上了哪些短板IndexedDB 补的核心短板可以概括成四个词大容量、结构化、异步、可索引。大容量没有 5MB 这种硬限制实际配额通常取决于浏览器和当前磁盘剩余空间比 localStorage 高两三个数量级。结构化直接存储对象原生支持 Date、Blob、ArrayBuffer、File 等类型不需要自己序列化成字符串。异步所有读写都是异步 API不阻塞 UI 渲染适合在页面正常交互的过程中做数据读写。可索引可以为对象仓库的字段建索引查询时直接走索引定位而不是把整张表捞出来线性过滤。光是这四点IndexedDB 就天然适合离线优先应用、数据量较大的前端缓存、以及需要复杂查询的场景。1.3 选型参考什么时候该用IndexedDB我现在的判断标准很简单场景存储方案用户偏好、简单标志位、一两百个字符串键值localStorage需要跨标签页共享且只读的少量配置localStorage几百条以上的结构化数据、需要按字段筛选排序IndexedDB离线优先应用、本地文件缓存BlobIndexedDB需要事务保证多条写入的一致性必须 IndexedDBlocalStorage 做不到另外说一个反直觉的结论IndexedDB 的 API 虽然不友好但它底层的设计思路并不复杂。真正劝退多数人的是它的回调风格和版本管理机制而不是数据库本身。接下来我会把这套机制一层层拆开拆完之后你会发现它其实和关系型数据库有很多共通之处。2. 建库之前先把数据库、对象仓库和索引这几个概念理顺2.1 图书馆类比数据库、对象仓库和索引各管什么IndexedDB 的层级结构可以想象成一个图书馆数据库database相当于一座图书馆本身没有太多结构就是对象仓库的集合。对象仓库object store相当于书架。关系型数据库里的“表”对应的就是 IndexedDB 里的“对象仓库”一张表里存什么对象类型一个仓库里也就存什么对象类型。索引index相当于图书目录索引它不真正存数据而是指向真实记录的位置。给对象的某个字段建索引后就可以按该字段高效查询和排序。游标cursor相当于一个移动的书签用来逐条遍历满足条件的数据。一个常见误区是把 IndexedDB 跟 localStorage 类比觉得它就是个“更大的 JSON 仓库”。这种误解会导致建模时把所有数据塞进一个对象仓库查询靠 getAll 后内存里过滤性能完全发挥不出来。正确的思路是像数据库一样对待它先规划对象仓库再为高频查询字段建立索引。下面这段代码展示了最基本的建库和建仓库逻辑const request indexedDB.open(taskDB, 1); request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(tasks)) { const store db.createObjectStore(tasks, { keyPath: id, autoIncrement: true }); store.createIndex(tag, tag, { unique: false }); store.createIndex(dueDate, dueDate, { unique: false }); store.createIndex(completed, completed, { unique: false }); } };2.2 主键与索引数据怎么被查得快对象仓库里的每条记录都是“键值对”形式值就是你要存的对象本身。键的指定方式有三种用 keyPath 指定对象里的某个字段作为主键用 autoIncrement 自动生成自增数字或者干脆在 add 时手动传一个外部键。主键的职责主要是唯一标识。而查询效率的开关其实在索引上。索引的本质是“字段值 → 主键”的映射。给 dueDate 建索引之后想查“所有到期日在今天之后的任务”可以直接通过索引拿到候选主键列表再回表取数据整个过程不需要全量扫描。索引的 unique 参数类似数据库中的唯一约束。比如邮箱、手机号这类字段可以设置 unique: true而 tag、status 这类重复度高的字段设置 unique: false。2.3 事务和异步API为什么要绕这一圈IndexedDB 的每个读写操作都发生在事务transaction里。事务保证一组操作要么全部成功、要么全部回滚这是 localStorage 根本不具备的能力。比如批量写入用户操作记录时中间任何一条写入失败前面写进去的数据也不会留下半截状态。在 API 层面IndexedDB 使用事件回调而不是 Promise。你调用 store.add() 时会得到一个 IDBRequest 对象真正的结果通过 request.onsuccess 或 request.onerror 返回。从开发体验上看确实比 fetch 那套繁琐一点但这并不影响实际使用——用一个 Promise 封装函数把回调包起来暴露出去的 API 就会非常顺手。这个封装我们在下一节案例里直接实现。另外要理解版本号的作用。indexedDB.open(dbName, version) 中的 version 不是数据库内容的版本号而是“结构版本号”。你只能在 onupgradeneeded 事件里创建、删除对象仓库、修改索引。如果你改了结构但没有提升版本号onupgradeneeded 就不会触发新结构自然也不会生效。这一点很多人第一次接触时都会踩坑后面会专门讲。3. 完整的任务清单案例数据库搭建与增删改查封装3.1 打开数据库并定义对象仓库先明确这个任务清单的数据结构。每条任务包含 id、title、tag、dueDate、completed 五个字段。我们的诉求是支持按标签过滤、按到期日期排序、按完成状态筛选所以建三个索引分别对应 tag、dueDate、completed。数据库版本号从 1 开始。onupgradeneeded 只在版本号升高时触发所以首次打开就会执行建表逻辑之后再次打开则直接进入 onsuccess。let db; function openDB() { return new Promise((resolve, reject) { const request indexedDB.open(taskDB, 1); request.onupgradeneeded (event) { const database event.target.result; if (!database.objectStoreNames.contains(tasks)) { const store database.createObjectStore(tasks, { keyPath: id, autoIncrement: true }); store.createIndex(tag, tag, { unique: false }); store.createIndex(dueDate, dueDate, { unique: false }); store.createIndex(completed, completed, { unique: false }); } }; request.onsuccess (event) { db event.target.result; resolve(db); }; request.onerror (event) { reject(event.target.error); }; }); }这个 openDB 函数里把 db 句柄缓存到模块级变量避免每次操作都重新打开数据库。在真实项目中建议在应用启动时先调用一次 openDB()等 onsuccess 之后再执行后续业务逻辑。如果项目里存在多个入口并发调用 openDB最好用一个 pending promise 做去重防止产生多个数据库连接。3.2 封装一组Promise风格的增删改查IndexedDB 里任何一个写操作都建议放在事务里读操作默认也会创建隐式事务。封装的核心套路是一致的创建事务 → 获取对象仓库 → 发起请求 → 监听事务的 oncomplete 或请求的 onsuccess 来决定何时 resolve。添加任务function addTask(task) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.add(task); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }注意事务的成功标志是 tx.oncomplete 而不是 store.add 的 onsuccess。因为事务里可能包含多条操作等到所有操作都提交完成、事务正常结束才是整个逻辑真正落库的时刻。更新任务时使用 put它会按主键整体替换记录function updateTask(task) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.put(task); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }需要注意updateTask 是整体覆盖。如果只想改 completed 一个字段得先 get 出整条记录修改字段后再 put 回去。否则原对象里其他字段会被清掉这是个非常隐蔽的数据丢失场景。删除任务function deleteTask(id) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); store.delete(id); tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); }读取单条记录function getTask(id) { return new Promise((resolve, reject) { const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const request store.get(id); request.onsuccess () resolve(request.result); request.onerror () reject(request.error); }); }3.3 用案例代码串一遍操作流程这些函数拼起来就是一个完整的清单功能。新增一条任务、查询全部任务、更新状态、删除任务核心代码可以这样串async function bootstrap() { await openDB(); await addTask({ title: 阅读文档, tag: 学习, dueDate: 2025-05-20, completed: false }); await addTask({ title: 整理笔记, tag: 学习, dueDate: 2025-05-21, completed: false }); await addTask({ title: 写周报, tag: 工作, dueDate: 2025-05-22, completed: true }); const task await getTask(1); console.log(读取单条:, task); const updated { ...task, completed: true }; await updateTask(updated); await deleteTask(2); }这段代码看着挺直观它把 IndexedDB 的“事务 回调”完全封装在 Promise 里业务层就只剩下普通的 async/await。我强烈建议在项目里先做一层这样的封装再在上层业务中使用否则每一处都要处理 IDBRequest 回调代码会迅速膨胀。4. 场景化查询用游标和索引过滤数据而不是全量读取后再筛选4.1 IDBKeyRange查询区间是怎么表达的刚刚的 getTask 只能按主键精确读取。但实际的清单应用里更多是“按日期范围”“按标签等于某个值”这类条件查询这时就要用 IDBKeyRange 来构造查询区间。IDBKeyRange 提供了几个静态方法// 只取某个值 IDBKeyRange.only(学习); // 大于等于某个值 IDBKeyRange.lowerBound(2025-05-20); // 小于等于某个值且不包含边界 IDBKeyRange.upperBound(2025-05-31, true); // 完整闭区间 IDBKeyRange.bound(2025-05-20, 2025-05-31, false, false);bound 的后两个参数分别表示下界和上界是否排除边界。这个规则看着啰嗦但确实是控制包含关系的唯一方式实际开发中别忘了调整。4.2 对象仓库游标与索引游标查询任务的正确姿势是先取索引再在索引上开游标。写一个“查找到期日落在某个区间的任务”function getTasksByDateRange(start, end) { return new Promise((resolve, reject) { const result []; const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const index store.index(dueDate); const range IDBKeyRange.bound(start, end, true, true); const request index.openCursor(range); request.onsuccess () { const cursor request.result; if (cursor) { result.push(cursor.value); cursor.continue(); } else { resolve(result); } }; request.onerror () reject(request.error); }); }这里最值得注意的地方是我们没有在内存里遍历整个仓库而是通过 dueDate 索引只读取目标日期范围内的记录。数据量到上万条时用 getAll 全量加载再 filter 会有明显的内存和时间开销而索引查询基本是毫秒级。4.3 用游标解决排序和分页索引还有一个隐藏能力排序。由于索引天然按键值排序索引游标默认就是按排序后的顺序输出。比如“按 dueDate 倒序”只需要给 openCursor 传入第二个参数 directionconst request index.openCursor(null, prev);null 表示不限范围prev 表示按索引值从大到小访问。同理还有 next、nextunique、prevunique后两个适用于去重查询。分页也可以靠游标实现思路是跳过前 offset 条再收集 limit 条function getTasksByTagWithPagination(tag, offset, limit) { return new Promise((resolve, reject) { const result []; let skipped 0; let fetched 0; const tx db.transaction(tasks, readonly); const store tx.objectStore(tasks); const index store.index(tag); const request index.openCursor(IDBKeyRange.only(tag)); request.onsuccess () { const cursor request.result; if (!cursor) { resolve(result); return; } if (skipped offset) { skipped; cursor.continue(); return; } result.push(cursor.value); fetched; if (fetched limit) { resolve(result); } else { cursor.continue(); } }; request.onerror () reject(request.error); }); }这里有个小技巧fetch 到 limit 条足够时直接 resolve函数返回后游标不再继续。readonly 事务自然会结束不必担心残留对象导致内存泄漏。5. 版本升级、事务生命周期说说我踩过的IndexedDB这几个坑5.1 TransactionInactiveError事务的隐形生命周期IndexedDB 最容易坑人的就是事务的自动提交机制。事务并不是你手动调 commit 才结束而是在所有请求完成后一旦控制权交回事件循环事务就可能自动提交。我之前写过一段自以为没问题的代码function brokenBatchAdd(tasks) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); tasks.forEach(async (task) { await fetchSomeData(); // 这里让出事件循环 store.add(task); // 可能抛 TransactionInactiveError }); }在 forEach 的 async 回调里fetchSomeData 会中断执行等网络请求返回时事务可能已经被浏览器自动提交了再往事务里 store.add 就会报 TransactionInactiveError。正确做法是把同一事务内的所有操作尽量同步地放入队列不要在事务处理过程中做 await 操作。如果需要先异步获取数据再写入应该等获取完成后再开启事务或者把 fetch 结果提前聚合成数组在一个事务内连续写入。这个错误信息前几次看到时很懵因为报错位置往往离真正的问题代码很远排查思路要从“事务是否还活跃”入手。5.2 onupgradeneeded只在版本升高时触发数据库结构升级必须走版本号。很多开发者会直接在全局代码里调用indexedDB.open(taskDB, 1);后来想加一个新索引就把代码里的版本号改成 2但直接改数字通常没用因为浏览器是根据当前数据库版本和传入版本号比较的。如果数据库已经是 1你现在传 2会触发升级但如果数据库已经是 2你再传 2什么都不会发生。结构总是比代码的版本演进缓慢这是正常的不代表代码有问题。升级逻辑一定放在 onupgradeneeded 里const request indexedDB.open(taskDB, 2); request.onupgradeneeded (event) { const database event.target.result; const tx event.target.transaction; if (!database.objectStoreNames.contains(projects)) { database.createObjectStore(projects, { keyPath: id }); } const store tx.objectStore(tasks); if (!store.indexNames.contains(priority)) { store.createIndex(priority, priority, { unique: false }); } };另一个容易忽视的点是升级事件里的 transaction 是升级事务在 onupgradeneeded 回调里可以继续拿它访问现有的 store 或新建的 store。但不要在 onupgradeneeded 里直接调用 db.close()升级事务还没结束强行关闭会抛异常。5.3 删除、索引和错误处理中的暗坑先看删除。deleteDatabase 调用之后旧的数据库对象并不会立即失效它得等到所有旧连接关闭后才真正开始删除。数据删除后磁盘空间的释放也是异步的浏览器通常要过一阵子才会回收。所以别用“删完立刻检查磁盘占用”这种方式来验证删除是否成功。再看索引。索引里的值如果为 undefined这条记录不会出现在该索引中。比如任务对象里某个任务没有 dueDate 字段那么按 dueDate 建的索引里就没有它按日期区间查询这个任务也查不到。这不是 bug而是设计如此。如果业务上要求这类记录也能被查询到需要给定一个默认值或者在写入前做字段兜底。最后说错误处理。IndexedDB 的 IDBRequest 有 onsuccess 和 onerror很多人只写了 onsuccess漏了 onerror。问题在于写操作失败时如果没有 onerror 监听你可能根本不知道数据没写进去页面还提示“保存成功”。在封装 Promise 时务必同时监听两个回调并把错误 reject 出去。前端开发里最可怕的数据问题不是报错而是“以为写进去了其实没有”。6. 批量写入、跨标签页同步以及如何把IndexedDB用得更顺手6.1 单事务内完成批量写入批量写入的要点是一个事务里连续执行多条 add 或 put。前面我们说过不要在里面 await 任何其他异步操作。一个事务内连续跑循环写入是安全的但如果数据量极大比如一次性写几万条也有可能导致事务长时间占用资源。稳妥的做法是分批次提交每批几百条批与批之间用 await 留出事件循环时间async function batchAddTasks(tasks) { const BATCH_SIZE 500; for (let i 0; i tasks.length; i BATCH_SIZE) { const batch tasks.slice(i, i BATCH_SIZE); await new Promise((resolve, reject) { const tx db.transaction(tasks, readwrite); const store tx.objectStore(tasks); for (const task of batch) { store.add(task); } tx.oncomplete () resolve(); tx.onerror () reject(tx.error); }); } }这种分批次写入既保证了事务的一致性边界又避免了一次事务执行太久导致浏览器限制或卡顿的隐患。6.2 跨标签页同步思路IndexedDB 本身的数据在每个标签页都是能读到的但一个标签页写入后另一个标签页不会自动得知。最轻量的方案是借助 BroadcastChannel 做通知写入完成后 postMessage 一个“数据已更新”的消息其他标签页收到后重新查询并刷新界面。const channel new BroadcastChannel(task-channel); // 写入成功后通知 await addTask(task); channel.postMessage(tasks-updated); // 其他标签页监听 channel.onmessage () { refreshTaskList(); };BroadcastChannel 不支持的环境就用 storage 事件兜底但注意 storage 事件只会在 localStorage 变化时触发IndexedDB 变化不会触发它。所以浏览器支持受限的环境下可以退化为定时轮询或手动监听 visibilitychange在页面重新可见时做一次刷新。6.3 封装思路把回调藏到底层我在项目里的习惯是所有 IndexedDB 操作永远不直接在业务代码里裸写 index.openCursor 这种逻辑而是统一封装成一个数据库模块。封装的核心是两件事第一把 IDBRequest 的 onsuccess/onerror 包装成 Promise第二把事务的 oncomplete/onabort 作为整个操作的完成信号。封装完以后业务侧只需要 import 一个包含 get、put、add、delete、query 的模块就能像操作一个普通异步数据库一样使用它。社区里其实也有不少把 IndexedDB 封装成 Promise 风格的工具库挑一个 star 多、维护积极的直接用也行。但如果想深入理解 IndexedDB 的机制我建议自己先写一遍封装这对后续排查问题帮助很大——出了奇怪报错时至少你知道它发生在请求层还是事务层。最后说一个调试技巧浏览器开发者工具的 Application 面板里有 IndexedDB 的实时查看功能可以展开库、对象仓库、索引看到每条记录的具体值也能手动删除记录。我每次做完数据库模块第一件事就是在这里写入几条测试数据肉眼确认索引是否建立、字段是否正确这比在控制台打日志直观得多。排查版本升级问题时也可以先看这里展示的当前数据库版本和仓库列表能少走不少弯路。