1. 项目概述为什么localStorage是Cocos Creator开发者的必备技能如果你正在用Cocos Creator开发游戏无论是微信小游戏、原生App还是Web版本有一个功能你几乎百分之百会用到那就是本地数据存储。想象一下玩家辛辛苦苦打到了第五关第二天打开游戏却要从头开始或者他精心调整的音量、画质设置每次重启游戏都要重新设置一遍——这种体验足以劝退大部分用户。而localStorage就是解决这个问题的“记忆核心”。它不是什么高深莫测的黑科技而是浏览器和许多运行环境提供的一个基础、轻量且极其关键的持久化存储方案。在Cocos Creator的语境下它更是我们实现游戏进度保存、用户偏好设置、本地缓存等功能的基石。别看它API简单用得好与不好直接关系到游戏的稳定性和用户体验。今天我就结合自己多年踩过的坑带你彻底吃透Cocos Creator中localStorage的方方面面从基础存取到高级技巧再到那些官方文档里不会写的“坑点”。2. 核心概念与运行环境解析2.1 localStorage的本质与限制首先我们必须明确localStorage到底是什么。它不是Cocos Creator独有的而是Web Storage API的一部分主要设计用于在浏览器端存储键值对key-value数据。其数据以字符串形式存储并且遵循同源策略。在Cocos Creator项目中当我们发布到Web平台或小游戏平台如微信小游戏、字节小游戏时我们使用的就是运行环境浏览器或小游戏容器提供的原生localStorage对象。它的核心特点决定了它的应用场景和限制存储容量通常为5MB左右因浏览器而异。这对于存储关卡进度、设置、一些简单的游戏状态如金币数、最高分绰绰有余但绝不适合存储大型资源如图片、音频。同步操作localStorage的读写是同步的。这意味着当你执行localStorage.setItem时浏览器会阻塞当前脚本直到写入完成。对于大量或频繁的写入可能会对主线程造成卡顿影响游戏帧率。仅支持字符串这是最容易出错的地方。localStorage只能存字符串。如果你直接存入一个数字、布尔值甚至对象它会被自动调用toString()方法。例如存入{score: 100}取出来就变成了[object Object]数据完全丢失。生命周期数据持久存在除非用户主动清除浏览器数据或我们通过代码删除。页面刷新、关闭浏览器甚至重启电脑数据都不会丢失。在Cocos Creator引擎内部其实对localStorage进行了一层简单的封装使其在不同平台下有一致的行为。但作为开发者我们通常直接使用cc.sys.localStorage这个接口它会在底层适配不同平台。2.2 Cocos Creator多平台适配浅析Cocos Creator的强大之处在于“一次开发多平台发布”。localStorage在不同平台下的实现略有差异Web平台直接使用浏览器的window.localStorage。行为最标准。微信小游戏引擎会使用微信小游戏提供的wx.setStorageSync和wx.getStorageSync等API进行模拟但对外暴露的依然是统一的cc.sys.localStorage接口。需要注意的是微信小游戏环境下的存储有单独的容量限制和清理策略。原生平台Android/iOS在打包成原生应用时Cocos Creator会使用原生提供的持久化存储方案如Android的SharedPreferencesiOS的NSUserDefaults来模拟localStorage的行为。这时数据存储的位置和生命周期就与App本身绑定。注意尽管引擎做了适配但在某些极端情况或深度定制需求下不同平台的细微差别可能会显现出来。例如原生平台的存储性能可能和浏览器有差异。因此对于核心数据充分的测试是必要的。3. 基础API详解与最佳实践3.1 增、删、改、查基础操作让我们从最基础的四个操作开始并附上代码示例和关键解释。1. 存储数据 (Create/Update)// 存储字符串 cc.sys.localStorage.setItem(playerName, CocosMaster); // 存储数字必须先转换为字符串 cc.sys.localStorage.setItem(highScore, String(9999)); // 或者更常用的存储为JSON cc.sys.localStorage.setItem(gameSettings, JSON.stringify({ musicVolume: 0.8, sfxVolume: 0.5, language: zh })); // 存储复杂对象标准做法 let playerData { level: 5, gold: 1200, items: [sword, potion], lastLogin: new Date().toISOString() }; cc.sys.localStorage.setItem(playerData, JSON.stringify(playerData));关键点setItem方法接受两个字符串参数。任何非字符串数据都必须序列化。JSON.stringify()是将对象转为字符串的标准且安全的方法。2. 读取数据 (Read)// 读取字符串 let name cc.sys.localStorage.getItem(playerName); // 返回 CocosMaster // 读取数字需要转换 let scoreStr cc.sys.localStorage.getItem(highScore); let highScore scoreStr ? parseInt(scoreStr, 10) : 0; // 安全转换避免NaN // 读取对象标准做法 let settingsStr cc.sys.localStorage.getItem(gameSettings); let gameSettings { musicVolume: 1.0, sfxVolume: 1.0 }; // 默认值 if (settingsStr) { try { gameSettings JSON.parse(settingsStr); } catch (e) { console.error(解析gameSettings失败使用默认值, e); } }关键点getItem可能返回null如果键不存在。永远不要假设数据一定存在或格式一定正确。使用前务必做空值判断和异常捕获特别是在解析JSON时。3. 删除数据 (Delete)// 删除单个键值对 cc.sys.localStorage.removeItem(tempData); // 根据id删除特定数据一个常见需求场景 // 假设我们存储了一个任务列表每个任务有id现在要删除id为‘task_003’的任务 let taskListStr cc.sys.localStorage.getItem(taskList); if (taskListStr) { let taskList JSON.parse(taskListStr); // 过滤掉指定id的任务 taskList taskList.filter(task task.id ! task_003); // 重新存储 cc.sys.localStorage.setItem(taskList, JSON.stringify(taskList)); }实操心得localStorage没有提供直接根据对象内部属性删除的API。所谓的“根据id删除”本质上是“读取 - 修改数据过滤 - 重新写入”的过程。这是一个非常典型的操作模式。4. 清空所有数据// 谨慎使用这会清除该域名下所有的localStorage数据。 cc.sys.localStorage.clear();警告clear()方法杀伤力极大通常只在游戏内的“清除所有数据”功能或开发调试时使用。在生产环境中调用需极其小心最好有二次确认提示。3.2 数据序列化与反序列化的艺术由于localStorage只认字符串JSON.stringify()和JSON.parse()就成了我们最亲密的伙伴。但这里面的门道不少。1. 处理循环引用和特殊类型JSON.stringify无法处理包含循环引用的对象、函数、undefined、Symbol等类型。存储游戏状态时要确保你的数据是“纯净”的POJOPlain Old JavaScript Object。// 错误示例 let player { name: A }; player.self player; // 循环引用 cc.sys.localStorage.setItem(p, JSON.stringify(player)); // 报错 // 正确做法存储前“净化”数据 let saveData { level: player.level, items: [...player.items] // 浅拷贝数组 // ... 只存储需要的基本属性 };2. 版本控制与数据迁移游戏更新后存储的数据结构可能会变。如何兼容旧版存档function loadPlayerData() { let dataStr cc.sys.localStorage.getItem(playerData); let data dataStr ? JSON.parse(dataStr) : {}; // 版本检查与迁移 const CURRENT_SAVE_VERSION 2; if (!data.version || data.version CURRENT_SAVE_VERSION) { data migrateSaveData(data); data.version CURRENT_SAVE_VERSION; savePlayerData(data); // 迁移后立即保存新版本 } return data; } function migrateSaveData(oldData) { // 从版本1迁移到版本2 if (oldData.version 1) { // 假设v1只有金币v2增加了钻石 oldData.gems 0; delete oldData.oldDeprecatedField; // 移除废弃字段 } // 可以有多级迁移判断 return oldData; }这是一个非常实用的技巧能确保游戏更新后老玩家的进度不会丢失或出错。4. 高级应用模式与性能优化4.1 封装健壮的存储管理器直接在业务代码中到处调用cc.sys.localStorage和JSON.parse/stringify是混乱且危险的。最佳实践是封装一个统一的存储管理模块例如StorageManager。// StorageManager.js export default class StorageManager { static setItem(key, value) { try { const str typeof value string ? value : JSON.stringify(value); cc.sys.localStorage.setItem(key, str); return true; } catch (error) { console.error(存储数据失败 [key: ${key}], error, value); // 这里可以尝试降级方案比如清理旧数据 if (error.name QuotaExceededError) { this._handleQuotaExceeded(); } return false; } } static getItem(key, defaultValue null) { try { const str cc.sys.localStorage.getItem(key); if (str null || str undefined) return defaultValue; // 尝试解析为JSON如果不是合法JSON则返回原始字符串 try { return JSON.parse(str); } catch (e) { return str; } } catch (error) { console.error(读取数据失败 [key: ${key}], error); return defaultValue; } } static removeItem(key) { cc.sys.localStorage.removeItem(key); } static _handleQuotaExceeded() { // 存储空间不足时的处理策略 console.warn(localStorage容量不足尝试清理过期或非核心数据); // 例如清理一些临时缓存键值 const tempKeys [temp_cache_, log_]; for (let i 0; i cc.sys.localStorage.length; i) { const key cc.sys.localStorage.key(i); if (tempKeys.some(prefix key.startsWith(prefix))) { this.removeItem(key); } } } } // 使用示例 import StorageManager from ./StorageManager; // 存对象 StorageManager.setItem(user, { id: 1, name: 玩家 }); // 取数据并指定默认值 const user StorageManager.getItem(user, { id: 0, name: Guest });这个管理器提供了错误处理、默认值、自动JSON转换和简单的容量溢出处理让业务代码更简洁安全。4.2 应对存储容量限制与性能考量5MB的容量对于纯文本的进度数据通常足够但如果你存储了大量Base64编码的小图片、复杂的关卡地图数据等可能会触顶。1. 监控使用量虽然无法精确获取已用量但可以通过估算来预警。function estimateLocalStorageSize() { let total 0; for (let i 0; i cc.sys.localStorage.length; i) { const key cc.sys.localStorage.key(i); const value cc.sys.localStorage.getItem(key); total (key.length value.length) * 2; // 每个字符约2字节UTF-16 } console.log(预估已使用存储: ${(total / 1024 / 1024).toFixed(2)} MB); return total; }2. 性能优化策略批量操作减少写入频率不要每获得一个金币就存一次盘。可以设置一个“脏标记”在游戏暂停、切场景、退出时统一保存。class GameData { constructor() { this._data { gold: 0, score: 0 }; this._isDirty false; } addGold(amount) { this._data.gold amount; this._isDirty true; // 可以设置一个定时器延迟保存避免频繁写入 this._scheduleSave(); } _scheduleSave() { if (this._saveTimer) return; this._saveTimer setTimeout(() { if (this._isDirty) { StorageManager.setItem(gameData, this._data); this._isDirty false; } this._saveTimer null; }, 2000); // 延迟2秒保存 } }数据压缩对于较长的字符串数据如序列化的关卡状态可以考虑简单的压缩。// 非常简单的示例使用LZString库进行压缩需引入 import LZString from lz-string; const largeData { /* 很大的对象 */ }; const compressed LZString.compressToUTF16(JSON.stringify(largeData)); StorageManager.setItem(largeLevelData, compressed); // 读取时解压 const compressedStr StorageManager.getItem(largeLevelData); const originalData JSON.parse(LZString.decompressFromUTF16(compressedStr));注意压缩/解压有CPU开销需权衡空间和时间的成本。5. 特定平台实践与疑难排查5.1 微信小游戏与打包APK的特殊性微信小游戏异步API微信原生提供了wx.setStorage和wx.getStorage的异步API性能更好。虽然cc.sys.localStorage用的是同步的Sync版本但在数据量大时你可以考虑直接调用微信的异步API进行封装避免阻塞游戏逻辑。清理策略微信小游戏平台可能会在存储空间紧张时自动清理非核心数据。不要将唯一的关键存档标识如用户ID完全依赖localStorage应考虑与微信的开放数据域或服务器进行关联。调试在微信开发者工具中可以在“Storage”面板中直接查看、修改、清除模拟的localStorage数据非常方便。打包APK原生平台存储路径数据最终存储在App的私有目录下用户无法直接通过文件管理器访问安全性更高。读写性能通常比浏览器环境更快更稳定。兼容性cc.sys.localStorage的接口是统一的但极少数情况下如果遇到问题可以检查Cocos Creator引擎版本或考虑使用更底层的jsb.fileUtils进行文件存储这是更进阶的方案。5.2 常见问题与调试技巧实录下面是我在实际开发中遇到的一些典型问题及解决方法整理成了速查表问题现象可能原因排查步骤与解决方案读取的数据是null或undefined1. 键名拼写错误。2. 数据从未被存储过。3. 数据已被clear()或removeItem()。1. 检查键名是否一致大小写敏感。2. 在存储后立即读取验证。3. 使用cc.sys.localStorage.getItem(‘key’)直接调试。存入对象后取出来是“[object Object]”直接存储了对象没有经过JSON.stringify()。永远记住存之前JSON.stringify()取之后JSON.parse()。使用封装的StorageManager可避免此问题。JSON.parse报错1. 存储的字符串不是合法JSON。2. 数据在存储过程中被破坏如部分写入。3. 编码问题。1. 用try...catch包裹JSON.parse。2. 检查存储逻辑确保写入是原子的。对于关键数据可考虑先写入临时键成功后再重命名为正式键。3. 避免存储二进制数据或特殊字符。存储空间不足(QuotaExceededError)存储数据总量超过5MB限制。1. 实现上述的容量估算和预警。2. 清理过期缓存、日志等非核心数据。3. 对大数据进行压缩。4. 考虑将部分数据转移到IndexedDBWeb或文件系统原生。在浏览器隐身模式下数据丢失大多数浏览器的隐身模式会在关闭窗口后清除localStorage。这是浏览器特性无法改变。在游戏启动时检测关键数据是否存在如果不存在则提示用户或初始化新游戏。不要依赖隐身模式下的持久化。微信小游戏中数据偶尔丢失可能触发了微信平台的自动清理或小游戏被系统销毁。1. 重要数据考虑在服务器备份。2. 利用微信的wx.setStorage异步API并做好成功回调判断。3. 在游戏生命周期事件如onHide中主动保存关键数据。调试技巧直接控制台操作在浏览器开发者工具的Console中可以直接输入cc.sys.localStorage或localStorage来查看、操作所有数据用于快速调试。键名命名规范建议使用清晰的前缀如game_settings、player_data_v2、cache_level_1。这便于管理和批量清理。版本化存储如前所述对数据结构进行版本号管理是应对游戏更新的最稳健方式。6. 实战构建一个完整的游戏存档系统让我们综合运用以上知识设计一个简易但健壮的游戏存档系统。这个系统需要处理玩家基础数据、多个关卡进度、以及系统设置。// GameSaveSystem.js export default class GameSaveSystem { static SAVE_KEY my_game_save_v1; // 版本化主键 // 默认存档结构 static DEFAULT_SAVE { version: 1, player: { name: 冒险者, level: 1, experience: 0, gold: 100, inventory: [] }, settings: { musicOn: true, sfxOn: true, volume: 0.7, language: zh }, progress: { // 关卡ID: 是否解锁最高星级是否通过 level_1: { unlocked: true, stars: 3, passed: true }, level_2: { unlocked: true, stars: 2, passed: true }, level_3: { unlocked: false, stars: 0, passed: false }, // ... }, lastSaveTimestamp: 0 }; // 加载存档 static load() { let saved StorageManager.getItem(this.SAVE_KEY); if (!saved) { // 没有存档创建默认 saved JSON.parse(JSON.stringify(this.DEFAULT_SAVE)); // 深拷贝默认值 this.save(saved); // 立即保存一份初始存档 return saved; } // 版本迁移示例 if (saved.version this.DEFAULT_SAVE.version) { saved this._migrateSave(saved); } // 合并默认值防止新版本增加字段导致undefined saved this._mergeWithDefault(saved, this.DEFAULT_SAVE); return saved; } // 保存存档 static save(saveData) { saveData.lastSaveTimestamp Date.now(); const success StorageManager.setItem(this.SAVE_KEY, saveData); if (success) { console.log(游戏存档成功); // 可以在这里触发一个存档成功的事件 // cc.systemEvent.emit(save-completed); } else { console.error(游戏存档失败); // 可以在这里提示玩家存储空间不足 } return success; } // 更新部分数据避免每次全量保存 static updatePartial(updates) { const currentSave this.load(); Object.assign(currentSave, updates); // 浅合并更新 return this.save(currentSave); } // 删除存档开始新游戏 static deleteSave() { StorageManager.removeItem(this.SAVE_KEY); console.log(存档已删除); } // --- 私有方法 --- static _migrateSave(oldSave) { const migrated JSON.parse(JSON.stringify(this.DEFAULT_SAVE)); // 复杂的迁移逻辑... // 例如将旧版的score字段迁移到新版的player.experience if (oldSave.version 1 oldSave.score ! undefined) { migrated.player.experience oldSave.score * 10; } // 保留能保留的旧数据 if (oldSave.player oldSave.player.name) { migrated.player.name oldSave.player.name; } migrated.version this.DEFAULT_SAVE.version; return migrated; } static _mergeWithDefault(target, source) { const result { ...target }; for (const key in source) { if (source.hasOwnProperty(key)) { if (result[key] undefined) { result[key] source[key]; } else if (typeof source[key] object source[key] ! null !Array.isArray(source[key])) { // 递归合并对象 result[key] this._mergeWithDefault(result[key] || {}, source[key]); } // 数组和基本类型以target为准已存在则不覆盖 } } return result; } } // 在游戏中的使用示例 // 游戏启动时 const currentSave GameSaveSystem.load(); console.log(欢迎回来${currentSave.player.name}); // 玩家获得金币时 currentSave.player.gold 50; // 方式一全量保存简单但频繁操作可能影响性能 // GameSaveSystem.save(currentSave); // 方式二部分更新推荐 GameSaveSystem.updatePartial({ player: { gold: currentSave.player.gold } }); // 通关一个关卡时 GameSaveSystem.updatePartial({ progress: { level_3: { unlocked: true, stars: 2, passed: true } } }); // 更改设置时 GameSaveSystem.updatePartial({ settings: { musicOn: false, volume: 0.5 } });这个存档系统体现了几个核心思想版本控制、默认值保障、数据合并、部分更新优化。它足够应对大多数中小型Cocos Creator游戏的本地存储需求。最后关于localStorage我的体会是它就像游戏开发中的“螺丝刀”工具本身简单但用得好不好全看使用者的心思。遵循“序列化、判空、容错、版本化”这几条基本原则封装一个适合自己的管理工具就能让这个基础功能变得无比可靠默默支撑起玩家的每一次进度留存。在考虑更复杂的数据库方案前不妨先把localStorage的潜力榨干。
Cocos Creator中localStorage的全面指南：从基础存储到高级存档系统
1. 项目概述为什么localStorage是Cocos Creator开发者的必备技能如果你正在用Cocos Creator开发游戏无论是微信小游戏、原生App还是Web版本有一个功能你几乎百分之百会用到那就是本地数据存储。想象一下玩家辛辛苦苦打到了第五关第二天打开游戏却要从头开始或者他精心调整的音量、画质设置每次重启游戏都要重新设置一遍——这种体验足以劝退大部分用户。而localStorage就是解决这个问题的“记忆核心”。它不是什么高深莫测的黑科技而是浏览器和许多运行环境提供的一个基础、轻量且极其关键的持久化存储方案。在Cocos Creator的语境下它更是我们实现游戏进度保存、用户偏好设置、本地缓存等功能的基石。别看它API简单用得好与不好直接关系到游戏的稳定性和用户体验。今天我就结合自己多年踩过的坑带你彻底吃透Cocos Creator中localStorage的方方面面从基础存取到高级技巧再到那些官方文档里不会写的“坑点”。2. 核心概念与运行环境解析2.1 localStorage的本质与限制首先我们必须明确localStorage到底是什么。它不是Cocos Creator独有的而是Web Storage API的一部分主要设计用于在浏览器端存储键值对key-value数据。其数据以字符串形式存储并且遵循同源策略。在Cocos Creator项目中当我们发布到Web平台或小游戏平台如微信小游戏、字节小游戏时我们使用的就是运行环境浏览器或小游戏容器提供的原生localStorage对象。它的核心特点决定了它的应用场景和限制存储容量通常为5MB左右因浏览器而异。这对于存储关卡进度、设置、一些简单的游戏状态如金币数、最高分绰绰有余但绝不适合存储大型资源如图片、音频。同步操作localStorage的读写是同步的。这意味着当你执行localStorage.setItem时浏览器会阻塞当前脚本直到写入完成。对于大量或频繁的写入可能会对主线程造成卡顿影响游戏帧率。仅支持字符串这是最容易出错的地方。localStorage只能存字符串。如果你直接存入一个数字、布尔值甚至对象它会被自动调用toString()方法。例如存入{score: 100}取出来就变成了[object Object]数据完全丢失。生命周期数据持久存在除非用户主动清除浏览器数据或我们通过代码删除。页面刷新、关闭浏览器甚至重启电脑数据都不会丢失。在Cocos Creator引擎内部其实对localStorage进行了一层简单的封装使其在不同平台下有一致的行为。但作为开发者我们通常直接使用cc.sys.localStorage这个接口它会在底层适配不同平台。2.2 Cocos Creator多平台适配浅析Cocos Creator的强大之处在于“一次开发多平台发布”。localStorage在不同平台下的实现略有差异Web平台直接使用浏览器的window.localStorage。行为最标准。微信小游戏引擎会使用微信小游戏提供的wx.setStorageSync和wx.getStorageSync等API进行模拟但对外暴露的依然是统一的cc.sys.localStorage接口。需要注意的是微信小游戏环境下的存储有单独的容量限制和清理策略。原生平台Android/iOS在打包成原生应用时Cocos Creator会使用原生提供的持久化存储方案如Android的SharedPreferencesiOS的NSUserDefaults来模拟localStorage的行为。这时数据存储的位置和生命周期就与App本身绑定。注意尽管引擎做了适配但在某些极端情况或深度定制需求下不同平台的细微差别可能会显现出来。例如原生平台的存储性能可能和浏览器有差异。因此对于核心数据充分的测试是必要的。3. 基础API详解与最佳实践3.1 增、删、改、查基础操作让我们从最基础的四个操作开始并附上代码示例和关键解释。1. 存储数据 (Create/Update)// 存储字符串 cc.sys.localStorage.setItem(playerName, CocosMaster); // 存储数字必须先转换为字符串 cc.sys.localStorage.setItem(highScore, String(9999)); // 或者更常用的存储为JSON cc.sys.localStorage.setItem(gameSettings, JSON.stringify({ musicVolume: 0.8, sfxVolume: 0.5, language: zh })); // 存储复杂对象标准做法 let playerData { level: 5, gold: 1200, items: [sword, potion], lastLogin: new Date().toISOString() }; cc.sys.localStorage.setItem(playerData, JSON.stringify(playerData));关键点setItem方法接受两个字符串参数。任何非字符串数据都必须序列化。JSON.stringify()是将对象转为字符串的标准且安全的方法。2. 读取数据 (Read)// 读取字符串 let name cc.sys.localStorage.getItem(playerName); // 返回 CocosMaster // 读取数字需要转换 let scoreStr cc.sys.localStorage.getItem(highScore); let highScore scoreStr ? parseInt(scoreStr, 10) : 0; // 安全转换避免NaN // 读取对象标准做法 let settingsStr cc.sys.localStorage.getItem(gameSettings); let gameSettings { musicVolume: 1.0, sfxVolume: 1.0 }; // 默认值 if (settingsStr) { try { gameSettings JSON.parse(settingsStr); } catch (e) { console.error(解析gameSettings失败使用默认值, e); } }关键点getItem可能返回null如果键不存在。永远不要假设数据一定存在或格式一定正确。使用前务必做空值判断和异常捕获特别是在解析JSON时。3. 删除数据 (Delete)// 删除单个键值对 cc.sys.localStorage.removeItem(tempData); // 根据id删除特定数据一个常见需求场景 // 假设我们存储了一个任务列表每个任务有id现在要删除id为‘task_003’的任务 let taskListStr cc.sys.localStorage.getItem(taskList); if (taskListStr) { let taskList JSON.parse(taskListStr); // 过滤掉指定id的任务 taskList taskList.filter(task task.id ! task_003); // 重新存储 cc.sys.localStorage.setItem(taskList, JSON.stringify(taskList)); }实操心得localStorage没有提供直接根据对象内部属性删除的API。所谓的“根据id删除”本质上是“读取 - 修改数据过滤 - 重新写入”的过程。这是一个非常典型的操作模式。4. 清空所有数据// 谨慎使用这会清除该域名下所有的localStorage数据。 cc.sys.localStorage.clear();警告clear()方法杀伤力极大通常只在游戏内的“清除所有数据”功能或开发调试时使用。在生产环境中调用需极其小心最好有二次确认提示。3.2 数据序列化与反序列化的艺术由于localStorage只认字符串JSON.stringify()和JSON.parse()就成了我们最亲密的伙伴。但这里面的门道不少。1. 处理循环引用和特殊类型JSON.stringify无法处理包含循环引用的对象、函数、undefined、Symbol等类型。存储游戏状态时要确保你的数据是“纯净”的POJOPlain Old JavaScript Object。// 错误示例 let player { name: A }; player.self player; // 循环引用 cc.sys.localStorage.setItem(p, JSON.stringify(player)); // 报错 // 正确做法存储前“净化”数据 let saveData { level: player.level, items: [...player.items] // 浅拷贝数组 // ... 只存储需要的基本属性 };2. 版本控制与数据迁移游戏更新后存储的数据结构可能会变。如何兼容旧版存档function loadPlayerData() { let dataStr cc.sys.localStorage.getItem(playerData); let data dataStr ? JSON.parse(dataStr) : {}; // 版本检查与迁移 const CURRENT_SAVE_VERSION 2; if (!data.version || data.version CURRENT_SAVE_VERSION) { data migrateSaveData(data); data.version CURRENT_SAVE_VERSION; savePlayerData(data); // 迁移后立即保存新版本 } return data; } function migrateSaveData(oldData) { // 从版本1迁移到版本2 if (oldData.version 1) { // 假设v1只有金币v2增加了钻石 oldData.gems 0; delete oldData.oldDeprecatedField; // 移除废弃字段 } // 可以有多级迁移判断 return oldData; }这是一个非常实用的技巧能确保游戏更新后老玩家的进度不会丢失或出错。4. 高级应用模式与性能优化4.1 封装健壮的存储管理器直接在业务代码中到处调用cc.sys.localStorage和JSON.parse/stringify是混乱且危险的。最佳实践是封装一个统一的存储管理模块例如StorageManager。// StorageManager.js export default class StorageManager { static setItem(key, value) { try { const str typeof value string ? value : JSON.stringify(value); cc.sys.localStorage.setItem(key, str); return true; } catch (error) { console.error(存储数据失败 [key: ${key}], error, value); // 这里可以尝试降级方案比如清理旧数据 if (error.name QuotaExceededError) { this._handleQuotaExceeded(); } return false; } } static getItem(key, defaultValue null) { try { const str cc.sys.localStorage.getItem(key); if (str null || str undefined) return defaultValue; // 尝试解析为JSON如果不是合法JSON则返回原始字符串 try { return JSON.parse(str); } catch (e) { return str; } } catch (error) { console.error(读取数据失败 [key: ${key}], error); return defaultValue; } } static removeItem(key) { cc.sys.localStorage.removeItem(key); } static _handleQuotaExceeded() { // 存储空间不足时的处理策略 console.warn(localStorage容量不足尝试清理过期或非核心数据); // 例如清理一些临时缓存键值 const tempKeys [temp_cache_, log_]; for (let i 0; i cc.sys.localStorage.length; i) { const key cc.sys.localStorage.key(i); if (tempKeys.some(prefix key.startsWith(prefix))) { this.removeItem(key); } } } } // 使用示例 import StorageManager from ./StorageManager; // 存对象 StorageManager.setItem(user, { id: 1, name: 玩家 }); // 取数据并指定默认值 const user StorageManager.getItem(user, { id: 0, name: Guest });这个管理器提供了错误处理、默认值、自动JSON转换和简单的容量溢出处理让业务代码更简洁安全。4.2 应对存储容量限制与性能考量5MB的容量对于纯文本的进度数据通常足够但如果你存储了大量Base64编码的小图片、复杂的关卡地图数据等可能会触顶。1. 监控使用量虽然无法精确获取已用量但可以通过估算来预警。function estimateLocalStorageSize() { let total 0; for (let i 0; i cc.sys.localStorage.length; i) { const key cc.sys.localStorage.key(i); const value cc.sys.localStorage.getItem(key); total (key.length value.length) * 2; // 每个字符约2字节UTF-16 } console.log(预估已使用存储: ${(total / 1024 / 1024).toFixed(2)} MB); return total; }2. 性能优化策略批量操作减少写入频率不要每获得一个金币就存一次盘。可以设置一个“脏标记”在游戏暂停、切场景、退出时统一保存。class GameData { constructor() { this._data { gold: 0, score: 0 }; this._isDirty false; } addGold(amount) { this._data.gold amount; this._isDirty true; // 可以设置一个定时器延迟保存避免频繁写入 this._scheduleSave(); } _scheduleSave() { if (this._saveTimer) return; this._saveTimer setTimeout(() { if (this._isDirty) { StorageManager.setItem(gameData, this._data); this._isDirty false; } this._saveTimer null; }, 2000); // 延迟2秒保存 } }数据压缩对于较长的字符串数据如序列化的关卡状态可以考虑简单的压缩。// 非常简单的示例使用LZString库进行压缩需引入 import LZString from lz-string; const largeData { /* 很大的对象 */ }; const compressed LZString.compressToUTF16(JSON.stringify(largeData)); StorageManager.setItem(largeLevelData, compressed); // 读取时解压 const compressedStr StorageManager.getItem(largeLevelData); const originalData JSON.parse(LZString.decompressFromUTF16(compressedStr));注意压缩/解压有CPU开销需权衡空间和时间的成本。5. 特定平台实践与疑难排查5.1 微信小游戏与打包APK的特殊性微信小游戏异步API微信原生提供了wx.setStorage和wx.getStorage的异步API性能更好。虽然cc.sys.localStorage用的是同步的Sync版本但在数据量大时你可以考虑直接调用微信的异步API进行封装避免阻塞游戏逻辑。清理策略微信小游戏平台可能会在存储空间紧张时自动清理非核心数据。不要将唯一的关键存档标识如用户ID完全依赖localStorage应考虑与微信的开放数据域或服务器进行关联。调试在微信开发者工具中可以在“Storage”面板中直接查看、修改、清除模拟的localStorage数据非常方便。打包APK原生平台存储路径数据最终存储在App的私有目录下用户无法直接通过文件管理器访问安全性更高。读写性能通常比浏览器环境更快更稳定。兼容性cc.sys.localStorage的接口是统一的但极少数情况下如果遇到问题可以检查Cocos Creator引擎版本或考虑使用更底层的jsb.fileUtils进行文件存储这是更进阶的方案。5.2 常见问题与调试技巧实录下面是我在实际开发中遇到的一些典型问题及解决方法整理成了速查表问题现象可能原因排查步骤与解决方案读取的数据是null或undefined1. 键名拼写错误。2. 数据从未被存储过。3. 数据已被clear()或removeItem()。1. 检查键名是否一致大小写敏感。2. 在存储后立即读取验证。3. 使用cc.sys.localStorage.getItem(‘key’)直接调试。存入对象后取出来是“[object Object]”直接存储了对象没有经过JSON.stringify()。永远记住存之前JSON.stringify()取之后JSON.parse()。使用封装的StorageManager可避免此问题。JSON.parse报错1. 存储的字符串不是合法JSON。2. 数据在存储过程中被破坏如部分写入。3. 编码问题。1. 用try...catch包裹JSON.parse。2. 检查存储逻辑确保写入是原子的。对于关键数据可考虑先写入临时键成功后再重命名为正式键。3. 避免存储二进制数据或特殊字符。存储空间不足(QuotaExceededError)存储数据总量超过5MB限制。1. 实现上述的容量估算和预警。2. 清理过期缓存、日志等非核心数据。3. 对大数据进行压缩。4. 考虑将部分数据转移到IndexedDBWeb或文件系统原生。在浏览器隐身模式下数据丢失大多数浏览器的隐身模式会在关闭窗口后清除localStorage。这是浏览器特性无法改变。在游戏启动时检测关键数据是否存在如果不存在则提示用户或初始化新游戏。不要依赖隐身模式下的持久化。微信小游戏中数据偶尔丢失可能触发了微信平台的自动清理或小游戏被系统销毁。1. 重要数据考虑在服务器备份。2. 利用微信的wx.setStorage异步API并做好成功回调判断。3. 在游戏生命周期事件如onHide中主动保存关键数据。调试技巧直接控制台操作在浏览器开发者工具的Console中可以直接输入cc.sys.localStorage或localStorage来查看、操作所有数据用于快速调试。键名命名规范建议使用清晰的前缀如game_settings、player_data_v2、cache_level_1。这便于管理和批量清理。版本化存储如前所述对数据结构进行版本号管理是应对游戏更新的最稳健方式。6. 实战构建一个完整的游戏存档系统让我们综合运用以上知识设计一个简易但健壮的游戏存档系统。这个系统需要处理玩家基础数据、多个关卡进度、以及系统设置。// GameSaveSystem.js export default class GameSaveSystem { static SAVE_KEY my_game_save_v1; // 版本化主键 // 默认存档结构 static DEFAULT_SAVE { version: 1, player: { name: 冒险者, level: 1, experience: 0, gold: 100, inventory: [] }, settings: { musicOn: true, sfxOn: true, volume: 0.7, language: zh }, progress: { // 关卡ID: 是否解锁最高星级是否通过 level_1: { unlocked: true, stars: 3, passed: true }, level_2: { unlocked: true, stars: 2, passed: true }, level_3: { unlocked: false, stars: 0, passed: false }, // ... }, lastSaveTimestamp: 0 }; // 加载存档 static load() { let saved StorageManager.getItem(this.SAVE_KEY); if (!saved) { // 没有存档创建默认 saved JSON.parse(JSON.stringify(this.DEFAULT_SAVE)); // 深拷贝默认值 this.save(saved); // 立即保存一份初始存档 return saved; } // 版本迁移示例 if (saved.version this.DEFAULT_SAVE.version) { saved this._migrateSave(saved); } // 合并默认值防止新版本增加字段导致undefined saved this._mergeWithDefault(saved, this.DEFAULT_SAVE); return saved; } // 保存存档 static save(saveData) { saveData.lastSaveTimestamp Date.now(); const success StorageManager.setItem(this.SAVE_KEY, saveData); if (success) { console.log(游戏存档成功); // 可以在这里触发一个存档成功的事件 // cc.systemEvent.emit(save-completed); } else { console.error(游戏存档失败); // 可以在这里提示玩家存储空间不足 } return success; } // 更新部分数据避免每次全量保存 static updatePartial(updates) { const currentSave this.load(); Object.assign(currentSave, updates); // 浅合并更新 return this.save(currentSave); } // 删除存档开始新游戏 static deleteSave() { StorageManager.removeItem(this.SAVE_KEY); console.log(存档已删除); } // --- 私有方法 --- static _migrateSave(oldSave) { const migrated JSON.parse(JSON.stringify(this.DEFAULT_SAVE)); // 复杂的迁移逻辑... // 例如将旧版的score字段迁移到新版的player.experience if (oldSave.version 1 oldSave.score ! undefined) { migrated.player.experience oldSave.score * 10; } // 保留能保留的旧数据 if (oldSave.player oldSave.player.name) { migrated.player.name oldSave.player.name; } migrated.version this.DEFAULT_SAVE.version; return migrated; } static _mergeWithDefault(target, source) { const result { ...target }; for (const key in source) { if (source.hasOwnProperty(key)) { if (result[key] undefined) { result[key] source[key]; } else if (typeof source[key] object source[key] ! null !Array.isArray(source[key])) { // 递归合并对象 result[key] this._mergeWithDefault(result[key] || {}, source[key]); } // 数组和基本类型以target为准已存在则不覆盖 } } return result; } } // 在游戏中的使用示例 // 游戏启动时 const currentSave GameSaveSystem.load(); console.log(欢迎回来${currentSave.player.name}); // 玩家获得金币时 currentSave.player.gold 50; // 方式一全量保存简单但频繁操作可能影响性能 // GameSaveSystem.save(currentSave); // 方式二部分更新推荐 GameSaveSystem.updatePartial({ player: { gold: currentSave.player.gold } }); // 通关一个关卡时 GameSaveSystem.updatePartial({ progress: { level_3: { unlocked: true, stars: 2, passed: true } } }); // 更改设置时 GameSaveSystem.updatePartial({ settings: { musicOn: false, volume: 0.5 } });这个存档系统体现了几个核心思想版本控制、默认值保障、数据合并、部分更新优化。它足够应对大多数中小型Cocos Creator游戏的本地存储需求。最后关于localStorage我的体会是它就像游戏开发中的“螺丝刀”工具本身简单但用得好不好全看使用者的心思。遵循“序列化、判空、容错、版本化”这几条基本原则封装一个适合自己的管理工具就能让这个基础功能变得无比可靠默默支撑起玩家的每一次进度留存。在考虑更复杂的数据库方案前不妨先把localStorage的潜力榨干。
