1. 基本概念与定位
1.1 什么是 IndexedDB
在现代浏览器端开发中，IndexedDB是一种结构化的客户端数据库，用于离线存储和复杂查询。它的设计目标是提供一个异步、事务性的键值数据库，以便在网络断开或离线场景下仍能稳定工作。通过对象存储（objectStore）、主键、索引（Index）等概念，开发者可以高效地管理和检索大规模数据集合。
与简单的 LocalStorage 相比，IndexedDB支持结构化数据、事务性操作与复杂查询，容量也远超前者，适合实现浏览器端的缓存、离线应用和离线数据同步等场景。
在实现上，IndexedDB 的操作是基于事务的异步模型，通过事件回调或 Promise 封装来完成数据读写，并保证数据的一致性和可靠性。对于前端开发者来说，熟悉 IDBDatabase、IDBTransaction、IDBObjectStore 等核心对象是进入此存储方案的关键。
// 简单检测浏览器是否支持 IndexedDB
if (!window.indexedDB) {console.log('IndexedDB 未被浏览器支持');
}
1.2 浏览器存储的定位与适用场景
在浏览器端，IndexedDB位于存储能力与 API 复杂度之间的一个平衡点。它适用于需要离线访问、离线缓存、批量写入与复杂查询的应用场景，例如本地笔记、离线新闻缓存、离线地图等。
相比于 LocalStorage，IndexedDB 支持大容量数据、二级索引、游标遍历，并且可以进行多笔写入的原子性操作，从而减少数据一致性问题。在隐私模式或私有浏览模式下，某些浏览器可能限制容量或清理策略，请留意浏览器差异。
2. 数据库模型与核心概念
2.1 数据库、对象存储、索引
IndexedDB 的核心单位是数据库，每个数据库包含若干对象存储（objectStore）。对象存储类似于一个集合，但具备更丰富的键路径设计，能够对每条记录设置主键。此外，索引（Index）用于提升查询效率，支持范围查询、前缀查询等。
通过键路径与自增键等方式，开发者可以控制数据的主键生成策略，并利用索引来快速定位目标记录。
// 打开数据库并在升级阶段创建对象存储与索引
const request = indexedDB.open('library', 1);
request.onupgradeneeded = function(event) {const db = event.target.result;const store = db.createObjectStore('books', { keyPath: 'isbn' });store.createIndex('by_title', 'title', { unique: false });
};
2.2 事务与异步模型
在 IndexedDB 中，所有写入与读取都必须在事务（Transaction）中执行，事务具备原子性、隔离性、持久性等特性。访问的对象存储通过IDBTransaction进行组合，IDBDatabase是连接数据库的入口。
API 采用事件驱动模式，常见事件包括onsuccess、onerror、onupgradeneeded等。在现代应用中，很多开发者会将这些回调包装成Promise或使用一些封装库来简化调用。
3. 实操指南：初始化与连接
3.1 初始化数据库与版本控制
创建或打开数据库时需要指定数据库名称以及版本号。当版本发生变化时，会触发onupgradeneeded事件，用于创建或更新对象存储和索引。
版本升级阶段是定义数据结构（对象存储及索引）的关键时刻，确保应用初始化后具备所需的结构。
const request = indexedDB.open('library', 2);
request.onupgradeneeded = (e) => {const db = e.target.result;if (!db.objectStoreNames.contains('books')) {const store = db.createObjectStore('books', { keyPath: 'isbn' });store.createIndex('by_title', 'title');}
};
request.onsuccess = (e) => {const db = e.target.result;// 使用 db 继续后续操作
};
3.2 切换、关闭与资源释放
数据库的操作需要通过事务来完成，一旦完成或出错就会进入complete或error状态。完成后应当关闭连接，以释放浏览器资源。
在页面关闭或导航离开时，适当处理onblocked事件，确保正在进行的事务不被中断导致数据丢失。
4. 实操指南：增删改查（CRUD）
4.1 添加数据
向对象存储中添加记录通常通过transaction与objectStore.add()完成。若主键已存在，操作会触发error，需要进行错误处理。
下面示例展示如何在一个事务中添加多条记录，确保在同一批次内完成提交。
function addBook(db, book) {const tx = db.transaction('books', 'readwrite');const store = tx.objectStore('books');const req = store.add(book);req.onsuccess = () => console.log('Added', book.isbn);req.onerror = () => console.error('Add failed');return tx.complete;
}
4.2 读取数据
数据读取可以使用get()、getAll()，以及基于索引的查询。游标（cursor）提供对结果集的遍历能力，适合分批处理。
以下示例演示按 ISBN 获取单条记录，以及按标题索引进行范围查询的基本用法。
function getBook(db, isbn) {return new Promise((resolve, reject) => {const tx = db.transaction('books', 'readonly');const store = tx.objectStore('books');const req = store.get(isbn);req.onsuccess = () => resolve(req.result);req.onerror = () => reject(req.error);});
}
function getBooksByTitle(db, title) {return new Promise((resolve, reject) => {const tx = db.transaction('books', 'readonly');const store = tx.objectStore('books');const index = store.index('by_title');const req = index.openCursor(IDBKeyRange.only(title));const results = [];req.onsuccess = (e) => {const cursor = e.target.result;if (cursor) {results.push(cursor.value);cursor.continue();} else {resolve(results);}};req.onerror = () => reject(req.error);});
}
4.3 更新与删除
更新通常通过put()来覆盖已有主键的记录，删除则使用delete()，clear() 可以清空对象存储。
下面示例展示按 ISBN 更新记录以及删除操作的实现。
function updateBook(db, book) {const tx = db.transaction('books', 'readwrite');const store = tx.objectStore('books');store.put(book); // 替换同一 isbn 的记录return tx.complete;
}
function deleteBook(db, isbn) {const tx = db.transaction('books', 'readwrite');const store = tx.objectStore('books');store.delete(isbn);return tx.complete;
}
5. 事务、事件与错误处理
5.1 事务模型与原子性
事务是对一组操作的原子执行单元，确保要么全部成功要么全部回滚，最大程度降低数据不一致的风险。在浏览器端，事务的生命周期由浏览器调度，完成状态与错误状态需要通过事件进行捕获。
理解事务边界、提交时机以及并发控制对编写稳定的 IndexedDB 代码至关重要。
5.2 错误、阻塞与事件回路
常见错误包括版本冲突、键冲突、以及浏览器资源限制带来的阻塞。通过监听onerror、onblocked、onupgradeneeded等事件，可以快速定位问题并实现降级策略。
将回调风格的 API 包装成Promise或async/await风格，可以显著提升可读性，同时保留 IndexedDB 的异步特性。
6. 性能优化与最佳实践
6.1 数据分区与对象存储设计
合理设计对象存储名称、键路径和索引，能显著提升查询效率。尽量将相关字段设计为索引列，避免在大量数据上执行全表扫描。
对于大对象或大数据集合，采用分批写入、分批读取与游标遍历，能够降低单次事务的阻塞概率与内存占用。
// 分批写入示例
async function batchAdd(db, items) {const tx = db.transaction('items', 'readwrite');const store = tx.objectStore('items');for (const item of items) {store.add(item);}return tx.complete;
}
6.2 兼容性与降级方案
并非所有旧浏览器都实现完整的 IndexedDB API，开发者应进行特性检测，并在必要时提供降级方案或使用替代存储。例如，条件性地回退到WebSQL或LocalStorage等方案（若浏览器仍有此能力）。
在现代浏览器中，IndexedDB 提供了稳定、强一致性与优秀的离线能力，是实现复杂离线应用的理想选择。
7. 兼容性、工具与生态
7.1 主流浏览器支持
Chromium、Firefox、Edge、Safari 等主流浏览器普遍支持 IndexedDB，核心 API 保持一致，版本差异通常较小，大多数 API 行为在不同引擎中是一致的。
使用时仍需注意隐私模式下的行为差异、容量限制以及长期存储策略，避免依赖单点不可用的实现。
7.2 辅助库与写法
为了简化回调地狱和 Promise 封装，可以使用专门的辅助库，例如 idb，提供基于 Promise 的 API，提升代码可读性与维护性。
// 使用 idb 库的示例
import { openDB } from 'idb';
async function addBookWithIdb() {const db = await openDB('library', 2, {upgrade(db) {const store = db.createObjectStore('books', { keyPath: 'isbn' });store.createIndex('by_title', 'title');}});await db.add('books', { isbn: '123-456', title: 'IndexedDB Guide' });
}
