存档与迁移:读取旧世界,提交新世界
存档是版本化协议
存档把一次游戏会话的状态带到下一次,实际上是在当前代码与未来代码之间传递协议。序列化成功只说明产生了字符串,不说明恢复后仍满足规则。应显式记录数据版本、写入序号与必要身份,保存真正需要恢复的状态;动画进度、节点引用、事件订阅和缓存通常不属于持久数据。后端经验在这里可以直接转化为模式校验、迁移和事务意识。
先按价值与生命周期分类。音量、语言、最高分可以本地保存;局内暂停点可能需要地图、实体、随机流和配置版本;付费资产、排行榜成绩和跨设备库存通常需要服务端可信状态。客户端加密只能增加修改门槛,密钥也可能在客户端可见,不能当作防作弊保证。不要让一个本地最高分例子被误认为已经实现账号与云存档。
模型保存编号和数值,恢复时重新连接关系。例如装备实例保存定义编号与耐久,不保存 Sprite 节点;任务保存进度与领取状态,不保存回调函数。派生属性可从等级和配置重建,但若配置会变化,需要决定过去状态按哪个版本恢复。这个决定属于产品规则,而不是 JSON 库自动处理的细节。
迁移按小步执行
type V1 = { version: 1; gold: number };
type V2 = { version: 2; wallet: { coins: number }; claimed: string[] };
function migrateOne(old: V1): V2 {
if (!Number.isSafeInteger(old.gold) || old.gold < 0) throw new Error('invalid gold');
return { version: 2, wallet: { coins: old.gold }, claimed: [] };
}
代码只是已经通过 V1 结构校验后的单步转换。实际加载链应是读取文本、解析未知值、检查版本、验证对应旧结构、依次迁移、验证当前结构、构建模型。不要用强制类型断言把旧数据直接变成新类型。迁移函数尽量纯粹,输入保持不变,输出可检查;失败时保留原始存档,避免一次更新把可恢复证据覆盖掉。
每个版本只负责迁到下一版,减少多条交叉路径。测试至少保留代表性旧存档夹具,验证迁移后余额、物品和进度符合约定。未来版本存档被旧客户端读取时应明确拒绝、只读或走兼容策略,不能当损坏档自动重置。所谓“自动修复”也要限定:缺少可选音量字段能补默认值,无法解释的资产负数不应随意归零。
写入失败与恢复策略
本地持久化可能因容量、环境或其他错误失败,调用需要捕获并给出可理解结果。可以维护当前档与上一份有效备份,给每份数据添加序号和校验和,启动时选择最新且结构有效的候选。校验和帮助发现截断或意外损坏,不证明数据可信。多键写入不应假定具有整体事务;采用单个完整快照,也仍需要理解具体平台的持久化保证。
若设计双槽保存,可先把新快照写入非当前槽并验证,再更新指针;启动时同时检查两个槽,不只相信指针。必须明确写入顺序及每一步失败后的恢复结果。对于教学小游戏,简单的单快照加备份可能已经足够,不必为了小型最高分记录建设复杂日志系统。资产价值越高,越应把权威提交放到服务端,而不是无限增加客户端保护层。
保存频率也要取舍。每帧同步写入会阻塞并造成不必要开销;只在退出时保存又可能丢失进度,因为进程不一定收到完整退出通知。可以在关键事务、关卡结算和合理间隔保存,并在隐藏事件中尽力补存。隐藏保存是补充保障,不是唯一保障。异步保存需要防止旧快照晚完成覆盖新快照,可用序号与串行队列控制。
奖励与存档需要同一个提交点
领取奖励时,余额增加与已领取标志应进入同一状态提交。否则崩溃后可能重复领取或丢失奖励。离线结算的时间水位也要和产出一起保存。UI 弹窗只是展示提交结果,不能把“点击关闭”当成奖励真正到账的时刻。多设备或网络环境下,需要服务端幂等键与冲突策略,不能把本地 Set 去重当成全局幂等。
Cocos Creator 3.8.8 可通过从 cc 导入的 sys 使用 localStorage 接口,复杂对象先序列化为 JSON。微信平台也有自己的存储 API,适配层应屏蔽具体差异并统一错误。不要在同一份游戏状态上随意混用两套键空间,还以为它们天然共享事务。平台容量与清理策略需核对当期官方说明,本文不承诺固定额度或永久保留。
常见恢复问题
“更新后全重置”先检查版本识别与键名是否变化;“最高分偶尔下降”检查旧异步写入覆盖新值以及是否用 max 合并;“背包出现重复物品”检查迁移是否每次启动重复执行;“一台设备正常另一台异常”检查账号隔离和配置版本;“存档有数据却读不到”检查解析、字符编码和存储适配器。
调试工具应能导出脱敏快照、显示版本与最近保存结果,并提供明确的开发重置入口。不要在生产错误处理里直接调用 clear 清空所有数据,它可能连设置和诊断证据也删除。恢复失败时向玩家说明哪些进度可用,并保留重试或联系支持的路径;不能显示“保存成功”却只更新了内存。
重置与导入也是写入操作
开发重置应显示将清除的键,导入存档则先完整校验并备份当前档,再执行替换。不要把调试粘贴的字符串直接当当前数据运行。导出用于诊断时应去除账号凭据和无关个人信息,保留版本、配置身份与复现所需状态。即使是个人教学项目,这些边界也能防止排错过程中意外丢失唯一一份可恢复进度。
给 AI 的任务与验收
任务示例:“实现最高分和设置的本地存档,版本从一迁移到二。加载按 unknown 校验,保留上一有效档;失败不覆盖原数据,未来版本明确拒绝。最高分按 max 合并,保存队列串行。提供可注入的内存存储用于模拟读写失败,不接云存档。”要求列出每个失败点的行为。
验收包括空档、合法旧档、损坏文本、缺字段、未来版本、写入抛错、连续保存与迁移后再重启。迁移两次启动不会重复加资产,保存失败不会伪报成功,重置只清本游戏明确管理的键。最后在实际运行环境验证读写与恢复;本文代码检查不能代替微信真机持久化测试。
来源与核查范围
- Cocos 3.8 用户数据存储,核查日期:2026-11-17。核对 JSON 存储与客户端安全边界;迁移和备份是本文方案。
- 微信官方小游戏 API 类型定义,核查日期:2026-11-17。核对存储接口;官方平台文档直连受限,容量与清理额度未在本文核定。