---

title: IndexedDB 版本升级与迁移：onupgradeneeded 的模式与实践

keywords:

• IndexedDB
• onupgradeneeded
• 版本迁移
• 事务
• 模式
• 性能

description: 总结 IndexedDB 的版本升级与模式（upsert/迁移脚本/幂等），解释 onupgradeneeded 回调中的对象仓库与索引变更、数据迁移与容错，并给出工程建议与参考。

tags:

• IndexedDB
• Web
• onupgradeneeded
• 事务
• 存储
• 工程化
• 性能
• 模式
• 版本迁移

categories:

• 文章资讯
• 编程技术

---

概述

IndexedDB 提供结构化存储与事务支持。版本升级通过 onupgradeneeded 回调进行模式变更（新建对象仓库、索引、迁移数据）。良好的迁移策略保证数据一致与可回退。

升级流程

• 打开数据库：const req = indexedDB.open('app', 3)；版本号变更触发 onupgradeneeded。
• 在回调中创建/修改对象仓库与索引：db.createObjectStore('users', { keyPath: 'id' })；为已有仓库添加索引：store.createIndex('email', 'email', { unique: true })［参考1,2］。
• 数据迁移：使用只读/读写事务遍历旧数据并写入新结构；确保幂等与错误回滚。

模式与实践

• 幂等迁移：检测仓库/索引是否存在再创建，避免重复错误。
• 小步升级：为每个版本号维护迁移脚本段落，按 oldVersion → newVersion 增量执行。
• 性能：批量迁移控制事务大小；避免在 UI 线程做大量计算，必要时分批或后台预处理。

工程建议

• 统一封装升级逻辑与版本映射；提供故障恢复与重试。
• 对关键数据备份与导出；在开发/灰度阶段进行迁移演练。

参考与验证

• ［参考1］MDN 中文：IndexedDB 概览与 open/onupgradeneeded/事务说明：https://developer.mozilla.org/zh-CN/docs/Web/API/IndexedDB_API
• ［参考2］MDN 英文：IndexedDB 使用与对象仓库与索引示例：https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB
• ［参考3］web.dev：IndexedDB 性能与模式实践（批量与事务）：https://web.dev/articles/indexeddb

关键词校验

关键词与 IndexedDB 版本迁移一致。