Godot 存档迁移测试夹具：版本升级时别赌玩家进度

存档系统最容易被低估。新功能上线前，团队通常会测试新建账号、新建存档、当前版本读写是否正常，却很容易忽略老玩家的真实存档。等版本发布后，才发现三个月前的存档缺少字段，某个任务状态无法迁移，或者背包里已经下架的道具让读取流程卡住。

Godot 客户端里，存档可能是 JSON、Resource、二进制或混合格式。无论格式如何，只要游戏持续更新，就需要迁移。迁移代码本身不难，难的是证明它覆盖了足够多的旧样本，并且失败时不会让玩家进度消失。

这篇文章关注存档迁移测试夹具。它不是另一个存档系统设计，而是在已有存档系统之上，建立旧版本样本库、迁移执行器、差异检查和回滚验证。目标很朴素：版本升级时，不拿玩家进度做赌注。

项目里的真实问题

一次版本更新中，策划把装备词条从字符串数组改成了结构化对象。新存档写入完全正常，内部测试也没有问题。但线上有一批老存档的装备词条为空数组，迁移脚本默认数组里至少有一个元素，结果读取时抛错。更麻烦的是，存档加载失败后客户端直接覆盖了自动存档，玩家失去了最后一个可恢复版本。

这类事故暴露了两个问题。第一，团队没有足够的旧样本，测试只覆盖了最近版本。第二，迁移流程没有事务概念，失败后污染了原始文件。迁移测试夹具要解决的正是这两个问题：拿真实或构造样本反复跑迁移，并确保失败不会破坏原文件。

存档迁移还会涉及内容变化。任务 id 被合并，地图入口被删除，角色属性重算，活动道具过期。迁移测试不能只检查“能读出来”，还要检查关键业务不变量：玩家等级不下降，货币不丢，主线任务有合法状态，背包物品都能解析。

目标和边界

• 样本可追溯：每个旧存档样本都有来源版本、覆盖点和预期结果。
• 迁移可重复：同一输入多次迁移得到同一输出，不能依赖随机或当前时间。
• 失败不污染：迁移前备份，迁移失败不覆盖原始存档。
• 自动断言：不只看日志，还要检查业务不变量和结构差异。

这些边界看起来像流程约束，实际是在保护客户端团队的节奏。Godot 项目一旦进入内容量增长阶段，很多问题并不是某个脚本写错了，而是编辑器、资源、运行时和发布流程之间没有明确交接点。把边界提前写清楚，可以减少临近提测时的争论，也能让新人知道应该在哪一层补逻辑。

推荐架构

flowchart TD
    A["旧版本存档样本库"] --> B["迁移测试夹具"]
    B --> C["复制到临时目录"]
    C --> D["执行迁移链"]
    D --> E["结构 schema 检查"]
    D --> F["业务不变量检查"]
    D --> G["差异报告"]
    E --> H{"通过"}
    F --> H
    H -- "是" --> I["记录基线"]
    H -- "否" --> J["保留输入/输出/日志"]

这张图不是为了追求复杂，而是把责任拆开。Godot 的便利之处在于 Node、Resource、信号和编辑器扩展都很轻，但便利也会诱导大家把判断写在任意脚本里。我的经验是，只要某个能力要被两个以上场景复用，就应该把它提升为一条稳定链路：输入是什么、谁负责校验、失败怎么回滚、日志如何被带出去。

建立旧存档样本库

样本库要覆盖版本跨度，而不是只保留最新几个。每次大版本发布前，固定导出一批代表性存档：新手、主线中段、满级、背包爆满、活动参与、异常恢复、云同步冲突后状态。样本可以脱敏，但结构必须真实。
每个样本旁边放一个 metadata，记录来源版本、账号阶段、覆盖功能和预期重点。比如 v1.3_bag_full_event_item 表示它用于检查活动道具过期后的迁移。这样半年后看到文件名，仍然知道它为什么存在。
不要只依赖真实玩家样本。真实样本覆盖自然路径，构造样本覆盖边界条件。比如空装备、未知任务 id、重复物品、负数计数、旧字段缺失，都应该有专门样本。迁移失败最常见的不是正常路径，而是历史版本留下的脏边界。

迁移链要可测试

迁移代码最好按版本拆成小步骤：1.2 -> 1.3、1.3 -> 1.4，而不是写一个巨大的 upgrade_to_latest。测试夹具可以从任意旧版本样本开始，按顺序执行迁移链。这样某一步出错时，日志能定位到具体版本段。
每个迁移步骤要尽量纯函数化：输入旧数据，输出新数据和变更摘要。不要在迁移中直接访问当前场景、UI 或网络。需要内容表参与时，把内容表版本作为参数传入。这样测试夹具才能在离线环境稳定运行。
迁移要有事务。先把原存档复制到临时路径，迁移成功并通过断言后，再原子替换正式文件。失败时保留原文件，并把错误写入恢复日志。Godot 里可以通过 user://save_migration_tmp 做中间目录，确保过程可清理。

业务不变量比 schema 更重要

schema 检查能发现字段缺失，但不能证明玩家进度正确。迁移测试必须加入业务不变量。例如玩家等级不能降低，已解锁关卡不能变少，货币不能凭空减少，装备引用的配置 id 必须存在，任务状态必须在允许枚举里。
差异报告要给人看。迁移前后背包数量、任务数量、货币、角色属性、已解锁节点都可以做摘要对比。测试失败时，开发应该能一眼看到是哪个系统变化异常，而不是打开几千行 JSON 手工查。
对于允许变化的字段，要显式声明。例如某次版本重算战力，战力变化是预期；活动道具过期后被兑换成补偿币，也是预期。把这些规则写进测试夹具，避免每次都靠口头解释。

GDScript 落地片段

class_name SaveMigrationHarness
extends RefCounted

func run_sample(sample_path: String, expected_version: int) -> MigrationResult:
    var work_path := "user://migration_tmp/save.json"
    DirAccess.make_dir_recursive_absolute(ProjectSettings.globalize_path("user://migration_tmp"))
    FileAccess.open(sample_path, FileAccess.READ).close()
    SaveTestFiles.copy(sample_path, work_path)
    var before := SaveCodec.read(work_path)
    var after := SaveMigrator.migrate_to_latest(before)
    var report := SaveInvariantChecker.check(before, after, expected_version)
    return report

这段代码不一定要原样放进项目，它更像接口形状的草图。真正落地时，我会先写成 Autoload 或 EditorPlugin 里的一个薄服务，让业务脚本只依赖稳定方法，不直接知道文件路径、远端地址、调试开关或平台差异。这样后续换实现时，场景脚本和 UI 脚本不需要跟着大面积调整。

排查指标

• 样本库覆盖的历史版本数量和功能标签数量。
• 每次迁移链执行耗时和失败步骤。
• 业务不变量失败类型分布。
• 发布前新增迁移样本数量以及线上读档失败率。

指标不要只在出问题后临时加。Godot 客户端经常遇到“编辑器里没事，导出包里才出问题”的情况，如果日志字段、采样频率和错误码命名没有提前约定，复盘时就只能靠截图和口头描述。建议把关键指标打印到本地日志，同时在内测包里接入轻量上报，至少保留设备、平台、场景、资源版本和玩家操作入口。

上线前检查清单

• 每个大版本至少保留一批代表性旧存档样本。
• 迁移步骤按版本拆分，日志能定位到具体步骤。
• 迁移先写临时文件，通过检查后再替换原文件。
• 测试同时检查 schema 和业务不变量。
• 失败样本保留输入、输出和迁移日志。

清单的价值不在于证明大家都很谨慎，而是把隐性经验变成团队共识。每次事故后都应该补一条能自动检查的规则，不能自动检查的也要变成明确的人工步骤。等同类问题第二次出现时，团队应该问的不是“谁又忘了”，而是“为什么流程还允许它被忘掉”。

分阶段落地和团队协作

第一阶段从最近三个版本的真实存档开始。每个版本挑新手、主线中段、满级和异常恢复四类样本，先跑通迁移链和不变量检查。样本不需要多，但必须能代表真实玩家路径。等工具稳定，再补构造边界样本。

第二阶段把迁移报告交给策划和 QA 一起看。报告里不要只有 JSON diff，还要有业务摘要：等级、货币、任务数量、背包数量、装备数量、已解锁关卡。策划能看懂这些摘要，才能判断某些变化是否符合设计预期。

第三阶段建立发布流程。任何存档结构变化都必须附带迁移步骤、样本更新和不变量更新。PR 模板里可以加一项“是否影响存档”，勾选后自动要求迁移测试结果。很多事故不是没人会写迁移，而是忘了这次改动需要迁移。

自动化验证和回归样本

自动化测试要覆盖从每个样本版本到最新版本的完整链路，也要覆盖重复迁移。重复迁移应该没有副作用，否则玩家在异常重启后可能被二次转换。测试还应模拟迁移中途失败，确认原始文件没有被覆盖。

构造样本要专门制造历史脏数据：未知任务 id、缺字段装备、重复道具、负数计数、过期活动状态、旧地图坐标。不要嫌这些样本难看，真实线上存档经常比设计文档复杂。迁移系统必须面对它们。

迁移代码 review 时重点看默认值和删除逻辑。新增字段默认值是否合理，旧字段删除前是否已经转换，无法映射的数据是否有补偿方案。最危险的写法是遇到未知数据直接丢弃。

灰度观察和事故复盘

灰度期建议只对少量玩家启用新迁移，并记录迁移耗时、失败原因和恢复路径。迁移失败时不要立刻覆盖自动存档，要保留备份并引导玩家上报。存档问题一旦扩大，修复成本会非常高。

如果出现读档失败事故，第一件事是保护现场。不要让客户端继续写入新存档覆盖旧文件。安全策略应该是保留原始存档、写失败标记、进入只读恢复界面，并把错误码和样本摘要导出。

长期看，存档迁移测试夹具会逼迫团队认真对待数据协议。每次结构变化都有样本，每次事故都有回归，每次发布都有迁移报告。玩家进度是客户端最不能随意试错的资产。

现场演练

现场演练可以从一份旧存档复制出三份：正常迁移、迁移中途模拟崩溃、迁移后业务断言失败。正常迁移要得到新版本存档；中途崩溃要保留原始文件和临时文件；业务断言失败要拒绝替换并输出差异报告。三种结果都清楚，发布时才不会在异常路径上慌张。

建议把演练结果给非程序同学看。策划能否理解“活动道具转换为补偿币”，QA 能否找到失败样本路径，客服能否根据错误码知道玩家该怎么恢复。存档迁移不是纯代码问题，它会直接影响玩家沟通。

边界补充

迁移夹具还应该检查性能边界。大型存档如果迁移耗时太长，玩家会以为游戏卡死。测试报告里要记录样本大小、迁移耗时和每个步骤耗时。必要时把迁移拆成启动前必要迁移和进入游戏后的后台补迁移，但拆分必须非常谨慎，不能让半迁移状态参与正常玩法。

另一个边界是隐私和脱敏。真实玩家存档用于样本库前，要移除账号标识、昵称、聊天记录和任何可能识别玩家的信息。迁移测试需要真实结构，不需要真实身份。这个流程提前做好，团队才敢长期积累样本。

小团队接入版本

小团队可以把迁移测试夹具做得很朴素：一个 save_samples 目录，一个运行脚本，一个输出 Markdown 报告。报告列出每个样本是否迁移成功、耗时多少、关键数值变化。只要它能在发版前跑起来，就已经比手动点几个存档可靠。

不要等存档系统完全成熟再补测试。越早开始积累旧样本，越能覆盖真实历史。很多迁移问题来自早期原型留下的字段，如果当时没有样本，半年后很难重新构造出来。

交付标准

交付标准可以定为：每个历史样本有来源说明，每次迁移有结构检查和业务检查，每次失败保留输入输出和日志。迁移测试不是为了让报告好看，而是为了在发布前给团队一个明确判断：这批旧玩家能不能安全升级。

如果项目支持云存档，还要把云端冲突样本纳入夹具。旧本地存档和新云端存档同时存在时，迁移顺序和冲突选择会影响结果。只测试单文件本地存档，无法覆盖真实运营环境。

交付补充

补充一点：迁移测试最好固定在发版分支创建后运行一次，在打包前再运行一次。前者发现结构问题，后者确认没有临时改动绕过迁移。两次报告都保留下来，线上出问题时才能追溯当时验证过哪些样本。

结语

存档迁移的风险不在代码量，而在历史包袱。Godot 项目只要持续运营，旧存档就会带着过去的设计一起走到今天。建立迁移测试夹具，是对老玩家时间的尊重，也是对客户端发布质量的基本保护。

补充落地笔记

早期样本库可以很小，但要真实。先准备 8 到 12 个覆盖核心路径的旧存档，放进仓库或受控测试数据目录。每次修复一个迁移 bug，就把触发 bug 的存档加入样本库。时间久了，这个目录会变成团队最有价值的升级安全网。