Phaser 存档迁移与版本化：从 LocalStorage 到可恢复数据管线

为什么要把它当成系统来做

游戏上线三个月后，背包从简单数组改成带格子尺寸的物品模型，任务系统也新增章节字段。老玩家打开游戏时，旧存档必须安全迁移；失败时不能让他们丢进度。

存档迁移不是发布前才补的脚本，而是从第一版就要设计的数据管线。Phaser 可以用 localStorage、IndexedDB 或平台 SDK，但核心是版本、校验、迁移和恢复。 本文不把它写成一个一次性 Demo，而是按可上线、可维护的小系统拆开。重点不是堆 API，而是回答几个真实问题：数据从哪里来，谁有权修改状态，失败时玩家看到什么，调试时程序能看到什么，内容增加后系统还能不能承受。

核心架构

flowchart TD
  Ne8afbbe58f["读取原始存档"] --> N5361766545["SaveEnvelope"]
  N5361766545["SaveEnvelope"] --> Ne78988e69c["版本检测"]
  Ne78988e69c["版本检测"] --> N4d69677261["MigrationRegistry"]
  N4d69677261["MigrationRegistry"] --> N56616c6964["Validator"]
  N56616c6964["Validator"] --> Ne5a487e4bb["备份旧档"]
  Ne5a487e4bb["备份旧档"] --> Ne58699e585["写入新档"]
  Ne58699e585["写入新档"] --> N5068617365["Phaser 场景恢复"]

这张图的关键，是把 SaveEnvelope、SchemaVersion、MigrationRegistry、Validator、BackupStore、ConflictResolver 放在单向流里。玩家输入或系统 tick 进入核心模型，模型产出结果，Phaser 再把结果转成动画、粒子、声音和界面。不要让显示对象反向决定规则。只要核心模型能在没有 Canvas 的环境中运行，就能写测试、做编辑器预览，也能在以后接入服务端校验或云存档。

存档要有信封结构

不要把玩家数据裸写进 localStorage。外层 SaveEnvelope 至少包含 schemaVersion、gameVersion、savedAt、checksum、profileId 和 payload。这样读取时先判断信封是否完整，再处理具体数据。未来上云、压缩或加密，也可以在信封层扩展，不影响玩法数据。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

迁移函数必须逐版本前进

从 v1 到 v4 不要写一个巨大的 if。维护 MigrationRegistry：v1 到 v2、v2 到 v3、v3 到 v4。读取旧档时按顺序执行。每个迁移函数只处理一个版本差异，输入输出都可测试。这样某个玩家从很老版本回归，也能经过同一条可靠路径。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

校验比迁移更重要

迁移完成后必须校验：货币非负、装备 id 存在、任务阶段合法、背包容量不超限、章节字段存在。校验失败时不要覆盖旧档，先保留备份并进入恢复流程。客户端可以提示玩家重试或使用最近备份，开发版则打印失败路径。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

备份策略要克制但存在

每次成功写入前保留一份 lastKnownGood，重大版本迁移前额外保留 preMigration。不要无限备份塞爆存储。备份里也要有信封和时间。迁移失败时，优先回退到 lastKnownGood；若当前旧档可读但新档不可写，提示空间问题。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

云存档冲突不能只按时间覆盖

云存档和本地存档可能都有进度。简单选择 savedAt 最新会误伤离线玩家。ConflictResolver 至少比较章节进度、游玩时长、货币变化和设备 id。对于无法自动判断的冲突，给玩家展示两个档案摘要，让玩家选择。选择结果也要记录，避免下次继续弹。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

Phaser 场景只拿已验证数据

Scene.create 不应该直接读取 localStorage。启动流程应先由 SaveService 读取、迁移、校验，得到 GameStateSnapshot，再进入游戏场景。若失败，进入存档恢复场景或主菜单提示。这样任何玩法场景都可以假设状态合法，不必到处防御旧字段。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

调试工具要能生成旧档

迁移测试需要样本。开发工具里准备生成 v1、v2、v3 存档的按钮，也能导入一段 JSON 运行迁移。每次改 schema 时，给迁移函数加测试样本。没有样本的迁移就是凭记忆写代码，迟早会伤到回归玩家。

在实现这一点时，建议先写一组可以复现的输入数据，再接 Phaser 场景。先让控制台打印出正确状态，再让 Graphics、Sprite、Text 和 Tween 去表现它。这样的顺序不炫，但能减少非常多“画面看起来对，规则其实错”的问题。

TypeScript 实现骨架

interface SaveEnvelope<T> { schemaVersion: number; savedAt: string; checksum: string; payload: T }
type Migration = (payload: any) => any;
const migrations = new Map<number, Migration>([
  [1, old => ({ ...old, quests: old.quests ?? [], chapter: 1 })],
  [2, old => ({ ...old, inventory: { slots: old.inventory ?? [], width: 8, height: 5 } })],
  [3, old => ({ ...old, settings: { language: "zh-CN", ...(old.settings ?? {}) } })],
]);
function migrate<T>(envelope: SaveEnvelope<any>, targetVersion: number): SaveEnvelope<T> {
  let version = envelope.schemaVersion;
  let payload = envelope.payload;
  while (version < targetVersion) {
    const step = migrations.get(version);
    if (!step) throw new Error(`Missing migration from v${version}`);
    payload = step(payload);
    version += 1;
  }
  return {
    ...envelope,
    schemaVersion: targetVersion,
    savedAt: new Date().toISOString(),
    checksum: "recalculate-before-write",
    payload,
  };
}

这段代码只是骨架，真正项目里还要加事件派发、错误码、配置校验和日志。但骨架已经表达了方向：核心概念是普通 TypeScript 对象，Phaser 类型只出现在输入适配或表现需要的地方。若你发现某个函数越来越依赖 Scene、Camera 或 Sprite，就应该停下来判断它是不是被放错层了。

落地步骤

1. 第一，确认 SaveEnvelope 的输入输出是否是纯数据。若需要 Phaser.GameObjects 才能计算结果，说明边界还没有切开。
2. 第二，给 SchemaVersion 或同等级的核心概念写三个最小样例：正常路径、边界路径、失败路径。样例要能在没有浏览器画面的情况下运行。
3. 第三，把 UI 上每个可点击动作都映射成明确意图，不要让按钮直接修改深层状态。意图里带 requestId，便于防重复和追踪。
4. 第四，失败反馈要比成功反馈更早接入。成功时玩家通常愿意接受，失败时才会质疑系统是否可靠。
5. 第五，内容配置要有默认值和校验脚本。字段缺失时宁可在启动时报错，也不要在玩家操作到一半才静默失败。
6. 第六，性能指标要提前量化：每帧最多处理多少对象、单次刷新允许多少毫秒、低端机是否需要降级显示。

常见坑

• 最容易踩的坑，是让表现层过早成为事实来源。比如动画播完才算成功、按钮亮着就代表可用、某个 Sprite 存在就说明状态存在。这些判断在演示机上没问题，一到跳过、暂停、断线、切场景和重连就会变成隐性故障。
• 第二个坑是只为第一关写逻辑。第一关对象少、路径短、输入慢，任何写法都像是正确的。等内容增加到几十张地图、几百个配置和各种活动修正时，临时判断会互相覆盖。写系统时要假设它会被复用、被误用、被配置错。
• 第三个坑是没有留下证据。玩家反馈“刚才没生效”时，如果没有事件日志、状态快照或 requestId，只能靠猜。哪怕是单机项目，也可以保留最近 50 条关键事件，开发包里导出文本，定位速度会快很多。

项目里的验证方式

把这套系统放进 Phaser 项目时，我会先建一个不依赖 Scene 的核心目录，例如 src/gameplay/save-migration-versioning。里面只放模型、求解器、状态机和测试夹具。Scene 只负责输入适配、对象池、摄像机、音效和 UI。这个边界看似多写几行代码，但它换来的是可测试、可回放和可迁移。等项目进入内容生产阶段，最值钱的不是某个特效多漂亮，而是当策划说某个状态不对时，程序能在五分钟内复现并解释。

数据格式要尽量像内容团队会填写的表，而不是像程序临时拼出来的对象。每个 id 都要稳定，每个状态都要能序列化，每个失败原因都要有明确枚举。Phaser 的优势是快速把反馈做出来，但反馈越快，越容易掩盖规则层的混乱。先把规则层写清楚，再接动画，后续加新模式、新活动或新平台才不会反复拆墙。

在调试阶段，建议给这个系统加一个小面板：显示当前输入、核心状态、最近事件、最后一次失败原因和关键耗时。面板不需要好看，但要准确。很多客户端问题在日志里只是一句 undefined，在调试面板里却能看到完整链路。尤其是多人、存档、复杂 UI 或长时间运行的玩法，调试可见性直接决定维护成本。

最后检查

做完第一版后，不要只看一次演示是否顺滑。至少准备三组数据：一组正常流程，一组边界流程，一组故意配置错误的流程。正常流程证明体验成立，边界流程证明状态不会漂移，错误流程证明系统会给出可理解的失败原因。存档迁移与版本化：从 LocalStorage 到可恢复数据管线 的质量不取决于第一眼多热闹，而取决于玩家反复操作、内容不断扩张、版本持续迭代时，它还能保持清楚、稳定和可解释。