游戏本地存档的数据结构升级后,如何兼容读取旧存档?
要让新版本游戏继续读取旧存档,关键不是让当前数据类“勉强兼容”所有历史字段,而是给存档明确标记结构版本,并在反序列化前按版本逐级转换。这样,旧存档能经过可控的迁移进入当前数据模型;遇到损坏文件或更新版本写出的存档时,游戏也不会误把它当成新游戏存档并覆盖。
下面用 C# 和 System.Text.Json.Nodes 演示一个从 v1、v2 迁移到 v3 的实现。示例面向 .NET 6 及以上版本,包含字段重命名、默认值补齐、基础校验和安全写回。具体字段和校验条件应根据项目的存档模型调整。
先明确每个版本的数据形状
假设早期 v1 把数据平铺在根节点中:
{
"version": 1,
"playerName": "Mira",
"level": 4,
"coins": 120,
"unlockedLevels": [1, 2, 3, 4]
}
后来 v2 将玩家、货币和关卡进度分组:
{
"version": 2,
"player": {
"name": "Mira",
"level": 4
},
"wallet": {
"softCurrency": 120
},
"progress": {
"unlockedLevels": [1, 2, 3, 4]
}
}
当前 v3 在此基础上增加音量设置:
{
"version": 3,
"player": {
"name": "Mira",
"level": 4
},
"wallet": {
"softCurrency": 120
},
"progress": {
"unlockedLevels": [1, 2, 3, 4]
},
"settings": {
"musicVolume": 1,
"sfxVolume": 1
}
}
version 表示的是存档数据结构版本,不一定等于游戏版本号。游戏修复问题或增加界面功能,不一定需要提升存档版本;只有存档字段结构、含义或约束发生变化时,才需要新增对应迁移。
用迁移链把旧结构转为当前结构
以下代码把版本转换与当前数据模型分开:先解析 JSON,再逐级迁移,最后反序列化并校验。迁移时只处理已知结构,不直接把旧 JSON 强行映射到新 DTO。

using System;
using System.IO;
using System.Linq;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
public sealed class SaveData
{
public int Version { get; set; } = 3;
public PlayerSave Player { get; set; } = new();
public WalletSave Wallet { get; set; } = new();
public ProgressSave Progress { get; set; } = new();
public SettingsSave Settings { get; set; } = new();
}
public sealed class PlayerSave
{
public string Name { get; set; } = "";
public int Level { get; set; } = 1;
}
public sealed class WalletSave
{
public int SoftCurrency { get; set; }
}
public sealed class ProgressSave
{
public int[] UnlockedLevels { get; set; } = { 1 };
}
public sealed class SettingsSave
{
public double MusicVolume { get; set; } = 1;
public double SfxVolume { get; set; } = 1;
}
public static class SaveCodec
{
private const int CurrentVersion = 3;
private static readonly JsonSerializerOptions JsonOptions = new()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
WriteIndented = true
};
public static SaveData Load(string path)
{
JsonNode? parsed;
try
{
parsed = JsonNode.Parse(File.ReadAllText(path));
}
catch (JsonException ex)
{
throw new InvalidDataException("存档不是有效的 JSON。", ex);
}
if (parsed is not JsonObject root)
throw new InvalidDataException("存档根节点必须是 JSON 对象。");
// 只有确认无 version 字段的历史文件确实符合 v1 结构时,
// 才应将缺少 version 的存档按 v1 处理。
int version = IntOr(root, "version", 1);
if (version < 1)
throw new InvalidDataException($"不支持存档结构版本 {version}。");
if (version > CurrentVersion)
throw new InvalidDataException(
$"存档结构版本为 {version},当前游戏只支持到 {CurrentVersion}。");
while (version < CurrentVersion)
{
root = version switch
{
1 => MigrateV1ToV2(root),
2 => MigrateV2ToV3(root),
_ => throw new InvalidDataException(
$"缺少从版本 {version} 开始的迁移逻辑。")
};
version++;
}
SaveData data;
try
{
data = root.Deserialize<SaveData>(JsonOptions)
?? throw new InvalidDataException("存档内容为空。");
}
catch (JsonException ex)
{
throw new InvalidDataException("存档字段与当前数据结构不匹配。", ex);
}
Validate(data);
data.Version = CurrentVersion;
return data;
}
public static void Save(string path, SaveData data)
{
Validate(data);
data.Version = CurrentVersion;
string fullPath = Path.GetFullPath(path);
string? directory = Path.GetDirectoryName(fullPath);
if (directory is null)
throw new InvalidOperationException("无法确定存档目录。");
Directory.CreateDirectory(directory);
// 临时文件放在目标文件同一目录,避免跨文件系统移动。
string tempPath = fullPath + ".tmp";
string json = JsonSerializer.Serialize(data, JsonOptions);
try
{
File.WriteAllText(tempPath, json, new UTF8Encoding(false));
File.Move(tempPath, fullPath, overwrite: true);
}
catch
{
try
{
if (File.Exists(tempPath))
File.Delete(tempPath);
}
catch
{
// 清理临时文件失败不应掩盖原始写入异常。
}
throw;
}
}
private static JsonObject MigrateV1ToV2(JsonObject old)
{
return new JsonObject
{
["version"] = 2,
["player"] = new JsonObject
{
["name"] = StringOr(old, "playerName", ""),
["level"] = IntOr(old, "level", 1)
},
["wallet"] = new JsonObject
{
["softCurrency"] = IntOr(old, "coins", 0)
},
["progress"] = new JsonObject
{
["unlockedLevels"] = CopyArrayOrDefault(
old, "unlockedLevels", defaultValue: 1)
}
};
}
private static JsonObject MigrateV2ToV3(JsonObject old)
{
JsonObject player = old["player"] as JsonObject ?? new JsonObject();
JsonObject wallet = old["wallet"] as JsonObject ?? new JsonObject();
JsonObject progress = old["progress"] as JsonObject ?? new JsonObject();
return new JsonObject
{
["version"] = 3,
["player"] = new JsonObject
{
["name"] = StringOr(player, "name", ""),
["level"] = IntOr(player, "level", 1)
},
["wallet"] = new JsonObject
{
["softCurrency"] = IntOr(wallet, "softCurrency", 0)
},
["progress"] = new JsonObject
{
["unlockedLevels"] = CopyArrayOrDefault(
progress, "unlockedLevels", defaultValue: 1)
},
["settings"] = new JsonObject
{
["musicVolume"] = 1.0,
["sfxVolume"] = 1.0
}
};
}
private static int IntOr(JsonObject obj, string key, int fallback)
{
if (!obj.TryGetPropertyValue(key, out JsonNode? node))
return fallback;
if (node is JsonValue value && value.TryGetValue<int>(out int result))
return result;
throw new InvalidDataException($"字段 {key} 不是有效整数。");
}
private static string StringOr(JsonObject obj, string key, string fallback)
{
if (!obj.TryGetPropertyValue(key, out JsonNode? node))
return fallback;
if (node is JsonValue value && value.TryGetValue<string>(out string? result))
return result ?? fallback;
throw new InvalidDataException($"字段 {key} 不是有效字符串。");
}
private static JsonArray CopyArrayOrDefault(
JsonObject obj, string key, int defaultValue)
{
if (!obj.TryGetPropertyValue(key, out JsonNode? node) || node is null)
return new JsonArray(JsonValue.Create(defaultValue));
if (node is JsonArray array)
return (JsonArray)array.DeepClone();
throw new InvalidDataException($"字段 {key} 不是数组。");
}
private static void Validate(SaveData data)
{
if (data.Player is null ||
data.Wallet is null ||
data.Progress is null ||
data.Settings is null)
{
throw new InvalidDataException("存档缺少必要的数据对象。");
}
if (data.Player.Level < 1 || data.Wallet.SoftCurrency < 0)
throw new InvalidDataException("存档中的等级或货币数值不合法。");
if (data.Progress.UnlockedLevels is null ||
data.Progress.UnlockedLevels.Length == 0 ||
data.Progress.UnlockedLevels.Any(level => level < 1))
{
throw new InvalidDataException("存档中的关卡进度不合法。");
}
if (data.Settings.MusicVolume is < 0 or > 1 ||
data.Settings.SfxVolume is < 0 or > 1)
{
throw new InvalidDataException("存档中的音量设置必须在 0 到 1 之间。");
}
}
}
项目中读取时调用 SaveCodec.Load(path),保存时调用 SaveCodec.Save(path, data)。从 v1 读取时,代码先运行 MigrateV1ToV2,再运行 MigrateV2ToV3;两次转换后才反序列化为 SaveData。因此每个迁移函数只需理解一个旧版本和它的直接后继,不需要在单个函数里堆叠所有历史分支。
默认值与字段变更要按业务含义处理
v2 没有音量字段,v2 到 v3 的迁移为两个音量设置填入 1.0。这代表新字段的默认行为,而不是单纯为了让反序列化通过。若新字段会影响游戏体验或数据权益,默认值应由产品规则决定;不能把所有缺失字段一律设成 0 或空值。
字段改名也应在迁移中显式处理,例如把 coins 转为 wallet.softCurrency。如果字段含义改变,则不只是改名:还需要明确单位换算、范围限制和舍入规则,并在迁移后验证结果。对可能造成玩家进度损失的字段,不宜在发现异常时静默重置为默认值;应保留原存档,记录可定位的错误,并让游戏进入可恢复的处理路径。
示例中的 CopyArrayOrDefault 会复制旧数组,避免迁移时直接复用带有父节点关系的 JsonNode。如果数组存在但类型不正确,代码会报出无效存档,而不是悄悄替换成默认关卡。这种区别很重要:字段缺失可能是旧版本的正常情况,字段类型错误则更可能意味着文件损坏或格式不符合预期。
缺少版本号和未来版本要单独处理
代码把没有 version 的文件按 v1 处理,这只适用于已确认早期存档确实是该格式的项目。如果历史上存在多种无版本号格式,应先依据稳定特征识别格式,或为每种格式提供单独入口;不能仅凭“没有版本号”就猜测结构。
当 version 大于当前支持版本时,示例会拒绝加载,而不是把未知格式当作当前版本解析。较新的游戏可能增加了旧客户端不认识的字段;旧客户端若把存档读成当前 DTO 并重新保存,还可能删掉这些未知字段。遇到该情况时,应保留原文件,提示玩家使用兼容版本打开,而不要自动创建空档覆盖它。
如果游戏有插件、模组或自定义扩展字段,当前示例的 DTO 反序列化和重新序列化不会自动保留所有未知字段。可为扩展数据保留独立节点,或使用能够保存未识别字段的机制;同时要明确不同扩展的命名空间和所有权,避免迁移代码误删其他组件的数据。
写回前保护原存档,并区分错误类型
Save 先写入同目录的临时文件,再移动到目标路径。这样可以减少进程在写入过程中退出时留下半份主存档的概率,但并不等于所有文件系统和断电场景下都能保证数据完整。高价值进度还应考虑保留轮换备份,并在写入失败时保留旧文件。

读取失败时,不要统一执行“新建默认存档并立即保存”。至少要区分以下情况:

- 文件不存在:可以按新游戏流程创建默认数据。
- JSON 解析失败或字段校验失败:保留原文件,提示玩家恢复备份或提交诊断信息。
- 存档版本高于当前客户端支持范围:不要用旧格式覆盖。
- 普通文件读取或权限错误:作为文件系统问题处理,不要误判为新游戏。
如果使用异步保存、多个存档槽或自动存档,需要额外管理并发写入。示例固定使用 path + ".tmp",因此同一路径不应被多个写入任务同时操作;可在存档服务中按槽位串行化写入,或为临时文件使用唯一名称,并在替换时仍确保只有一个任务提交目标文件。
用旧样本验证迁移链
准备每个历史版本的代表性存档,至少覆盖正常数据、缺少可选字段、边界数值和错误类型。将样本送入 Load 后,检查返回数据是否符合当前业务模型;再用 Save 写出,确认输出包含当前版本号和新字段。迁移测试还应验证旧文件未被意外修改,尤其是在解析失败和版本过新时。
例如,v1 样本中的 coins: 120 应进入 Wallet.SoftCurrency,关卡数组应保留原值,新增的两个音量字段应取设定的默认值;再次保存后,输出应标记为 v3。测试时可把输入文件复制到临时目录,避免直接用真实玩家档案做破坏性验证。

迁移函数最好保持确定性:同一份 v1 输入重复转换,得到的当前数据应一致;迁移本身不应执行奖励发放、联网同步或其他可能重复产生副作用的操作。需要在迁移中调整进度或补偿数据时,应让变更规则可追踪,并为重复加载和失败重试设计清楚行为。
采用版本号和逐级迁移后,新版客户端只需维护从受支持旧版本到当前版本的转换链。发布前保留历史样本并验证读取、写回和异常分支;如果仍需支持更早的无版本格式,则把它们作为明确的输入格式单独覆盖,而不是依赖反序列化器猜测。
当游戏需要把本地存档进一步接入云端备份、跨设备同步或历史样本管理时,A5数据可提供香港、美国、日本、新加坡等地区的物理服务器与SSD、NVMe及大容量存储资源,支持承载存档接口、数据服务和备份归档;结合域名、SSL证书与CDN,也可为游戏后台入口及资源访问提供相应的网络配套。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9936.html