首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >IndexedDB 版本迁移:为什么升级后老用户打不开数据库

IndexedDB 版本迁移:为什么升级后老用户打不开数据库

原创
作者头像
跨境出海观察员
发布于 2026-11-16 09:04:43
发布于 2026-11-16 09:04:43
120
举报

“昨天还好好的,今天一打开就报数据库版本错误。”IndexedDB 的版本迁移是前端存储里最容易出问题的一环。版本号、升级事务、旧连接和阻塞事件,任何一处处理不好,用户就会卡在打不开数据库的状态。

一、版本号不是普通字段

indexedDB.open(name, version) 的第二个参数是数据库版本。第一次创建时,版本从 1 开始;之后每次结构变更,都要把版本号加一。浏览器会比较请求版本和当前版本:

  • 请求版本高于当前版本,触发 upgradeneeded;
  • 请求版本等于当前版本,直接打开;
  • 请求版本低于当前版本,抛出 VersionError。

所以不要用“当前时间戳”当版本号,也不要在不同分支里写不同的版本号;版本号一旦上线,只能递增,不能回退。

indexedDB.databases() 可以列出当前源下的数据库,但拿不到版本;要查版本只能打开后读 db.version。调试时先确认浏览器里实际版本,再比对代码里的常量。

二、升级事务里做什么

onupgradeneeded 是唯一可以修改对象仓库和索引的阶段。它运行在一个 versionchange 事务里,所有建表、建索引操作都必须在这个事务内完成。

代码语言:javascript
复制
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 事务里用游标复制:

代码语言:javascript
复制
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,在事件里关闭旧连接:

代码语言:javascript
复制
db.onversionchange = () => {
  db.close();
  alert('数据库已更新,请刷新页面');
};

同时,页面卸载时也要 db.close();单页应用切换路由时,别忘了关闭不再使用的连接。监听 versionchange 时,除了关闭连接,还要通知用户刷新;否则新版本打开后,旧页面继续用旧连接,下一次升级又会被 blocked。

四、多账号环境的边界

IndexedDB 按 origin 存储,和 Cookie、localStorage 是不同层。清 Cookie 不会删除 IndexedDB;同一个浏览器 profile 下切换账号,数据库仍然共享。不同 profile 才会各自独立。

对多账号运营来说,这意味着“换账号”不等于“换存储”。如果业务把账号数据写进 IndexedDB,切换前要确认数据库是否按账号分区,或者直接使用独立 profile。

五、排查清单

  1. 控制台是 VersionError 还是 blocked;
  2. db.version 与代码里的版本常量是否一致;
  3. 是否监听了 versionchange 并关闭旧连接;
  4. 迁移逻辑是否都在 upgradeneeded 里完成;
  5. 迁移失败后是否回滚、是否保留旧仓库。

六、总结

IndexedDB 版本迁移的核心是:版本号只增不减、结构变更放在 upgradeneeded、旧连接在 versionchange 里关闭、迁移前先备份。排查“打不开”时,先看控制台是 VersionError 还是 blocked,再决定是改版本号还是关旧标签页。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、版本号不是普通字段
  • 二、升级事务里做什么
  • 三、旧连接会阻塞升级
  • 四、多账号环境的边界
  • 五、排查清单
  • 六、总结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档