1. 项目概述为什么Cocos开发者必须关注Web存储如果你正在用Cocos Creator开发Web游戏或应用那么“数据存哪”这个问题迟早会变成一个让你头疼的“坑”。项目初期你可能随手就用cc.sys.localStorage存了用户分数和设置一切看起来都挺好。但随着项目迭代需求来了要存用户的关卡编辑数据、要缓存大量的音频/图片资源以减少加载时间、要实现断点续玩……这时候你可能会发现LocalStorage开始“力不从心”存大了会报错、存多了会卡顿、异步操作还得自己封装。这正是我们今天要深入对比的两种核心Web存储方案LocalStorage 和 IndexedDB。它们不是Cocos引擎独有的但却是Cocos Web端项目最常打交道的两个浏览器原生存储接口。选择哪一个直接关系到你应用的性能上限、用户体验和代码的复杂程度。网上有很多泛泛而谈的对比但今天我们只聚焦于Cocos开发者的实际场景从一个小游戏的存档到一个复杂编辑器应用的本地缓存我们该如何根据需求做技术选型如何避开那些文档里没写的“坑”2. 核心方案解析LocalStorage与IndexedDB的本质差异要做出正确选择不能只看API调用是否简单必须理解两者底层设计的根本不同。这决定了它们的适用场景天花板。2.1 LocalStorage简单直接的“文本保险箱”你可以把LocalStorage想象成一个在浏览器里为你每个网站同源策略下分配的一个小型、永久的“文本保险箱”。这个保险箱结构极其简单它只认“键值对”key-value而且键和值都必须是字符串。核心特性与限制同步操作任何读写都是同步的。localStorage.setItem(‘score’, ‘1000’)这行代码会阻塞主线程直到写入完成。数据量小时无感但当你尝试存入一个几MB的字符串时页面会有明显的“卡顿”。存储容量通常每个源域名有5MB左右的限制。这个限制是浏览器强制的超出会抛出QuotaExceededError异常。数据类型只能存字符串。这意味着你想存一个对象必须先JSON.stringify取出来再用JSON.parse。对于数字、布尔值存取时会有隐式的类型转换需要注意。适用场景用户偏好设置如音量、语言、简单的游戏状态如最高分、当前关卡、登录令牌等小型、结构简单的数据。在Cocos中我们通常通过cc.sys.localStorage这个接口来访问它是对浏览器原生LocalStorage的一个兼容性封装用法基本一致。2.2 IndexedDB浏览器内的“迷你数据库”如果说LocalStorage是保险箱IndexedDB就是一个功能完整的、非关系型的对象数据库。它允许你存储大量结构化数据甚至是文件Blob。核心特性与优势异步操作所有核心API打开数据库、创建事务、读写数据都是基于事件的异步操作。这意味着它不会阻塞页面渲染和JavaScript主线程对复杂应用和游戏的流畅度至关重要。海量存储存储上限远高于LocalStorage通常是硬盘空间的某个百分比如50%理论上可达数百MB甚至GB级足以应对资源缓存等重型任务。存储对象直接存储JavaScript对象无需序列化为字符串。还支持存储ArrayBuffer、Blob等二进制数据非常适合缓存图片、音频等资源文件。索引查询可以像数据库一样在对象的某些属性上建立索引从而实现高效的查询而不仅仅是按键取值。事务支持保证了数据操作的原子性避免在复杂操作中数据出现不一致的状态。一个常见的误解是IndexedDB API非常复杂。的确它的回调风格旧版或Promise风格新版比LocalStorage的一行代码要繁琐。但对于Cocos项目我们完全可以通过封装一个轻量级的工具库来简化使用这也是为什么像“vue3 封装一个indexeddb的增删改存的库”会成为热词——大家需要的是友好的抽象层。3. 场景化选型指南在Cocos项目中如何抉择脱离场景谈技术选型都是空谈。下面我们结合Cocos项目从简单到复杂的几种典型需求来分析该如何选择。3.1 场景一轻度小游戏与H5营销页典型需求保存最高分、游戏音效开关、当前解锁关卡。数据特点数据量极小100KB结构固定且简单读写频率低。选型推荐LocalStorage理由杀鸡焉用牛刀。LocalStorage的同步API在Cocos里用起来极其方便cc.sys.localStorage.setItem/getItem两行代码搞定没有异步回调的心理负担。5MB的容量对于这种场景绰绰有余。开发速度快代码简洁。3.2 场景二中度复杂游戏如Roguelike、模拟经营典型需求保存玩家复杂的装备库、技能树、地图探索进度、生成的随机种子。数据特点数据量可能达到几百KB结构是复杂的嵌套对象需要整体保存和加载。选型推荐需评估但IndexedDB优势渐显详细分析如果单个存档对象经过JSON.stringify后的大小稳定在1-2MB以下且加载存档不是高频操作如只在游戏开始/结束时LocalStorage勉强可用。但你要警惕JSON.stringify大对象本身可能就是性能瓶颈。如果存档结构复杂或未来有扩展可能强烈建议使用IndexedDB。你可以将整个存档作为一个对象存储享受异步加载不卡顿的好处。更重要的是如果你的存档数据有查询需求例如“快速找到所有‘传说’品质的武器”LocalStorage需要全部加载后手动遍历而IndexedDB可以通过索引实现高效查询。3.3 场景三重度应用与编辑器如Cocos游戏编辑器、UGC创作平台典型需求缓存项目资源纹理、声音、预制体数据、保存多版本项目历史、离线编辑。数据特点数据量巨大数十MB以上包含大量二进制资源需要事务性操作保证数据完整性。选型推荐IndexedDB唯一选择理由这是IndexedDB的主场。LocalStorage的5MB限制在第一关就被淘汰了。IndexedDB可以直接存储Blob格式的图片或音频文件作为资源缓存池能极大提升二次加载速度。它的异步特性确保了在后台加载缓存资源时UI界面依然流畅响应。事务机制可以安全地处理“保存项目”这种涉及多个对象存储的复杂操作。3.4 场景四需要“根据id删除”的列表型数据典型需求管理本地保存的多个游戏存档、用户本地生成的草图列表。操作特点需要灵活的增删改查而不仅仅是覆盖整个数据集。选型推荐IndexedDB实操对比LocalStorage要实现删除一条记录你需要1getItem取出整个列表数组字符串2JSON.parse成数组3用filter等方法找到并删除对应id的项4JSON.stringify转回字符串5setItem写回。这个过程繁琐且对于大列表效率低。IndexedDB在对应的对象存储ObjectStore上直接调用delete(ID)方法即可。这是数据库级别的原生删除操作高效且简单。这正是热词“根据id删除localstorage数据”背后反映的痛点——开发者用LocalStorage模拟数据库操作时感到的别扭。4. Cocos中的实战封装与代码示例理解了理论我们来看看在Cocos Creator以TypeScript为例中如何具体使用和封装它们。4.1 LocalStorage的基础与进阶用法基础用法Cocos已经封装好了很简单// 存数据 cc.sys.localStorage.setItem(‘playerScore’, ‘10000’); cc.sys.localStorage.setItem(‘gameSettings’, JSON.stringify({ sound: true, music: false })); // 取数据 const score cc.sys.localStorage.getItem(‘playerScore’); // “10000” const settings JSON.parse(cc.sys.localStorage.getItem(‘gameSettings’) || ‘{}’); // 删数据 cc.sys.localStorage.removeItem(‘playerScore’);进阶封装建议 对于稍微复杂点的数据建议封装一个管理器统一处理序列化和错误。export class StorageManager { static setObject(key: string, value: any): boolean { try { const str JSON.stringify(value); cc.sys.localStorage.setItem(key, str); return true; } catch (error) { console.error(LocalStorage写入失败 (key: ${key}):, error); // 这里可以尝试清理旧数据或提示用户 return false; } } static getObjectT(key: string, defaultValue: T): T { const str cc.sys.localStorage.getItem(key); if (!str) return defaultValue; try { return JSON.parse(str) as T; } catch (error) { console.error(LocalStorage解析失败 (key: ${key}):, error); return defaultValue; } } // 还可以封装remove、clear等方法 } // 使用 StorageManager.setObject(‘inventory’, myWeaponsList); const savedSettings StorageManager.getObject(‘settings’, { volume: 0.5 });4.2 IndexedDB的封装策略与核心操作直接使用原生IndexedDB API确实繁琐。我们的目标是封装一个简洁的、Promise化的工具类。以下是一个高度精简但功能完整的封装示例export class IndexedDBWrapper { private dbName: string; private version: number; private db: IDBDatabase | null null; constructor(dbName: string, version: number 1) { this.dbName dbName; this.version version; } // 打开或创建数据库 open(storeName: string, keyPath?: string, indexes?: { name: string; keyPath: string; unique?: boolean }[]): PromiseIDBDatabase { return new Promise((resolve, reject) { const request indexedDB.open(this.dbName, this.version); request.onerror () reject(request.error); request.onsuccess () { this.db request.result; resolve(this.db); }; // 仅在版本更新时触发用于创建或更新对象存储和索引 request.onupgradeneeded (event) { const db (event.target as IDBOpenDBRequest).result; if (!db.objectStoreNames.contains(storeName)) { const objectStore db.createObjectStore(storeName, { keyPath: keyPath || ‘id’ }); if (indexes) { indexes.forEach(index { objectStore.createIndex(index.name, index.keyPath, { unique: index.unique || false }); }); } } }; }); } // 增/改数据 put(storeName: string, data: any): PromiseIDBValidKey { return new Promise((resolve, reject) { if (!this.db) return reject(‘Database not opened.’); const transaction this.db.transaction([storeName], ‘readwrite’); const store transaction.objectStore(storeName); const request store.put(data); request.onerror () reject(request.error); request.onsuccess () resolve(request.result); }); } // 根据主键查询 get(storeName: string, key: IDBValidKey): Promiseany { return new Promise((resolve, reject) { if (!this.db) return reject(‘Database not opened.’); const transaction this.db.transaction([storeName], ‘readonly’); const store transaction.objectStore(storeName); const request store.get(key); request.onerror () reject(request.error); request.onsuccess () resolve(request.result); }); } // 根据索引查询高效查询的关键 getByIndex(storeName: string, indexName: string, value: any): Promiseany[] { return new Promise((resolve, reject) { if (!this.db) return reject(‘Database not opened.’); const transaction this.db.transaction([storeName], ‘readonly’); const store transaction.objectStore(storeName); const index store.index(indexName); const request index.getAll(value); // 获取所有匹配项 request.onerror () reject(request.error); request.onsuccess () resolve(request.result); }); } // 根据主键删除呼应热词需求 delete(storeName: string, key: IDBValidKey): Promisevoid { return new Promise((resolve, reject) { if (!this.db) return reject(‘Database not opened.’); const transaction this.db.transaction([storeName], ‘readwrite’); const store transaction.objectStore(storeName); const request store.delete(key); request.onerror () reject(request.error); request.onsuccess () resolve(); }); } }在Cocos项目中的使用示例// 1. 初始化并打开数据库 const db new IndexedDBWrapper(‘MyGameDB’, 2); async function init() { await db.open(‘gameSaves’, ‘saveId’, [ { name: ‘playerIdIdx’, keyPath: ‘playerId’, unique: false } // 为playerId创建非唯一索引 ]); console.log(‘数据库准备就绪’); } // 2. 保存一个复杂的游戏存档 const gameSave { saveId: ‘slot_1’, playerId: ‘user_123’, timestamp: Date.now(), level: 10, inventory: [...], // 复杂对象数组 worldState: { ... } // 庞大的嵌套对象 }; await db.put(‘gameSaves’, gameSave); // 3. 读取存档 const savedData await db.get(‘gameSaves’, ‘slot_1’); // 4. 查询某个玩家的所有存档利用索引 const allUserSaves await db.getByIndex(‘gameSaves’, ‘playerIdIdx’, ‘user_123’); // 5. 删除一个存档 await db.delete(‘gameSaves’, ‘slot_1’);5. 性能、兼容性与实操避坑指南5.1 性能实测与感知差异对于用户而言两种方案最直接的感知差异在于“卡顿”。LocalStorage写入一个5MB的字符串主线程可能会被阻塞100-200毫秒甚至更久。在这期间动画会掉帧输入无响应。这是一个需要避免的“性能雷区”。IndexedDB写入同样大小的数据因为是异步操作主线程几乎无感。回调函数会在数据写入磁盘后执行。这对于保存大型游戏状态或缓存资源时保持UI流畅至关重要。量化建议如果你的单次存储操作可能超过100KB就应该严肃考虑使用IndexedDB。5.2 兼容性现状与降级策略LocalStorage兼容性极好几乎所有支持Cocos Web的平台都支持。IndexedDB在现代浏览器中支持良好包括移动端。主要需要注意微信内置浏览器的某些旧版本可能存在兼容性问题或性能差异。降级策略对于要求极高的生产环境可以实现一个“存储适配层”。interface IStorage { save(key: string, data: any): Promiseboolean; load(key: string): Promiseany; } class AdaptiveStorage implements IStorage { private useIndexedDB: boolean false; private idbWrapper: IndexedDBWrapper | null null; async init() { if (‘indexedDB’ in window) { try { this.idbWrapper new IndexedDBWrapper(‘GameData’); await this.idbWrapper.open(‘mainStore’); this.useIndexedDB true; } catch (e) { console.warn(‘IndexedDB初始化失败降级至LocalStorage’, e); this.useIndexedDB false; } } } async save(key: string, data: any) { if (this.useIndexedDB this.idbWrapper) { await this.idbWrapper.put(‘mainStore’, { id: key, value: data }); } else { // 降级到LocalStorage注意大小限制 const success StorageManager.setObject(key, data); if (!success) { throw new Error(‘存储失败可能超出容量限制’); } } return true; } // … load方法类似 }5.3 常见问题与排查技巧实录问题1LocalStorage存满了怎么办现象调用setItem时抛出QuotaExceededError。排查首先检查单条数据是否过大。其次检查是否存储了太多历史或临时数据。解决压缩数据对于JSON可以使用JSON.stringify的替换函数移除不必要的空格或使用更高效的序列化库如msgpack-lite。清理旧数据建立有效的清理机制例如只保留最近10条存档。数据分片将一个大对象拆分成多个键存储如gameState_part1,gameState_part2但此法治标不治本。终极方案迁移至IndexedDB。问题2IndexedDB操作失败但错误信息很模糊。现象控制台只显示一个DOMException不知道具体哪步出错。排查技巧监听所有事件务必为onerror、onsuccess、onupgradeneeded都设置好处理函数。检查事务模式写操作put, delete, clear必须在readwrite事务中进行。验证数据结构存入的数据对象必须包含定义好的keyPath属性如上面的saveId。版本号问题如果修改了数据库结构如新增对象存储或索引必须增加version号否则onupgradeneeded不会触发修改不生效。问题3如何调试IndexedDB中存储的内容Chrome DevToolsApplication面板 - Storage - IndexedDB。在这里你可以直观地看到所有数据库、对象存储和里面的数据记录支持直接编辑和删除是调试神器。Firefox DevToolsStorage面板 - IndexedDB功能类似。问题4Cocos小游戏平台如微信小游戏的特殊性微信小游戏环境并非标准浏览器其存储方案是自有的wx.setStorage和wx.setStorageSync。Cocos Creator在发布到小游戏平台时cc.sys.localStorage会自动适配到这些平台API。但IndexedDB在小游戏平台不可用。应对策略如果你的项目需要同时发布Web和微信小游戏并且使用了IndexedDB你需要针对小游戏平台再封装一层在Web端用IndexedDB在小游戏端用wx.getStorage/setStorage。这可以通过Cocos Creator的条件编译CC_WECHATGAME来实现。6. 混合使用策略与未来展望在实际的大型Cocos项目中混合使用两者往往是更优解。策略冷热数据分离热数据高频、小体积存LocalStorage如游戏设置、当前会话的临时状态。利用其同步特性随时快速存取。冷数据低频、大体积存IndexedDB如用户的所有存档、缓存的资源包、日志文件。利用其大容量和异步特性不影响主线程性能。展望Cache API与OPFSCache API属于Service Worker的一部分主要用于缓存网络请求如图片、脚本。对于需要HTTP语义的资源缓存它比IndexedDB更专业。Origin Private File System (OPFS)这是一个更新的浏览器特性它提供了一个真正的文件系统接口允许高性能、同步的二进制文件读写。对于需要像原生应用一样操作大量文件例如一个大型3D模型的资源包的Cocos项目OPFS可能是未来的终极解决方案。但目前其兼容性还远未普及。对于绝大多数Cocos Web项目而言掌握好LocalStorage和IndexedDB的二分法已经能解决99%的本地存储问题。核心原则就是轻量、同步、简单的用LocalStorage重量、异步、复杂的用IndexedDB。理解它们背后的原理根据你的项目数据和访问模式做出合理选择并在编码初期就做好适当的封装这将为你的项目打下坚实的数据层基础避免后期重构的巨大成本。