“昨天还好好的,今天一打开就报数据库版本错误。”IndexedDB 的版本迁移是前端存储里最容易出问题的一环。版本号、升级事务、旧连接和阻塞事件,任何一处处理不好,用户就会卡在打不开数据库的状态。
indexedDB.open(name, version) 的第二个参数是数据库版本。第一次创建时,版本从 1 开始;之后每次结构变更,都要把版本号加一。浏览器会比较请求版本和当前版本:
upgradeneeded;VersionError。所以不要用“当前时间戳”当版本号,也不要在不同分支里写不同的版本号;版本号一旦上线,只能递增,不能回退。
indexedDB.databases() 可以列出当前源下的数据库,但拿不到版本;要查版本只能打开后读 db.version。调试时先确认浏览器里实际版本,再比对代码里的常量。
onupgradeneeded 是唯一可以修改对象仓库和索引的阶段。它运行在一个 versionchange 事务里,所有建表、建索引操作都必须在这个事务内完成。
const req = indexedDB.open('app', 3);
req.onupgradeneeded = () => {
const db = req.result;
if (!db.objectStoreNames.contains('orders')) {
const store = db.createObjectStore('orders', { keyPath: 'id' });
store.createIndex('byUser', 'userId');
}
};
req.onblocked = () => {
console.warn('还有旧标签页占用数据库,请关闭后重试');
};如果需要迁移旧仓库的数据,可以在同一个 versionchange 事务里用游标复制:
const old = req.transaction.objectStore('orders');
const next = db.createObjectStore('orders_v2', { keyPath: 'id' });
old.openCursor().onsuccess = (event) => {
const cursor = event.target.result;
if (!cursor) return;
next.put(cursor.value);
cursor.continue();
};复制完成前不要删除旧仓库;确认新仓库数据完整后,再在后续版本里清理。
事务是自动提交的:所有请求完成后会 commit,除非触发 abort()。迁移时不要在事务里做异步的 fetch 或 setTimeout,事务会提前结束。
新增对象仓库或索引比较简单;重命名、删除字段、改变主键,通常要新建仓库、迁移数据、再删旧仓库。迁移过程中不要先删旧数据,否则失败后无法回滚。
如果升级失败,onerror 会收到错误,事务回滚;不要忽略这个事件。onabort 也要处理,否则用户只看到“打不开”,看不到原因。
只要还有旧标签页持有数据库连接,新版本升级就会进入 blocked 状态,用户看到的是“一直打不开”。正确做法是监听 versionchange,在事件里关闭旧连接:
db.onversionchange = () => {
db.close();
alert('数据库已更新,请刷新页面');
};同时,页面卸载时也要 db.close();单页应用切换路由时,别忘了关闭不再使用的连接。监听 versionchange 时,除了关闭连接,还要通知用户刷新;否则新版本打开后,旧页面继续用旧连接,下一次升级又会被 blocked。
IndexedDB 按 origin 存储,和 Cookie、localStorage 是不同层。清 Cookie 不会删除 IndexedDB;同一个浏览器 profile 下切换账号,数据库仍然共享。不同 profile 才会各自独立。
对多账号运营来说,这意味着“换账号”不等于“换存储”。如果业务把账号数据写进 IndexedDB,切换前要确认数据库是否按账号分区,或者直接使用独立 profile。
VersionError 还是 blocked;db.version 与代码里的版本常量是否一致;versionchange 并关闭旧连接;upgradeneeded 里完成;IndexedDB 版本迁移的核心是:版本号只增不减、结构变更放在 upgradeneeded、旧连接在 versionchange 里关闭、迁移前先备份。排查“打不开”时,先看控制台是 VersionError 还是 blocked,再决定是改版本号还是关旧标签页。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。