用JsonUtility在Unity里实现游戏存档（含Vector3、枚举处理与数据恢复实战）
在游戏开发中，数据持久化是绕不开的核心需求。想象一下：玩家辛苦打了3小时的Boss战，突然游戏崩溃，所有进度清零——这种体验足以让任何玩家愤怒卸载。而一个健壮的存档系统，不仅能避免这种灾难，还能实现多设备同步、多存档位等增强体验的功能。
Unity内置的JsonUtility虽然不如第三方库功能全面，但胜在轻量高效、无需额外依赖，特别适合处理游戏对象的序列化需求。本文将手把手带你构建一套完整的存档系统，重点解决三个开发者常遇到的痛点：
- Vector3等Unity特有类型的序列化：角色位置、旋转等数据的保存与还原
- 枚举值的智能处理：避免存档中只存数字导致的可读性差问题
- 数据版本兼容：游戏更新后旧存档仍能正常读取的解决方案
1. 存档系统架构设计
1.1 确定数据存储范围
典型的游戏存档需要包含这些核心元素：
[System.Serializable] public class GameSaveData { public string saveVersion; // 用于版本兼容 public Vector3 playerPosition; public PlayerState currentState; // 枚举类型 public InventoryItem[] inventory; // 数组类型 public Dictionary<string, bool> unlockedAchievements; // 需特殊处理 }注意：直接使用Dictionary会导致序列化失败，需要额外处理方案
1.2 选择存储位置
Unity提供几种常见的持久化路径：
| 存储位置 | 适用场景 | 访问方式 |
|---|---|---|
| Application.persistentDataPath | 跨平台安全存储 | 推荐首选 |
| PlayerPrefs | 简单键值对 | 不适合复杂数据 |
| 云存储 | 多设备同步 | 需后端支持 |
1.3 版本控制策略
建议采用语义化版本号管理存档：
public const string CURRENT_VERSION = "1.2.0"; // 在保存时自动注入版本号 saveData.saveVersion = CURRENT_VERSION;这样在读取时可以做版本比对，实现旧版存档的自动迁移。
2. 处理特殊数据类型
2.1 Vector3的完美序列化
JsonUtility原生支持Unity的常用数学类型：
// 保存示例 Vector3 playerPos = transform.position; string json = JsonUtility.ToJson(playerPos); // 读取还原 Vector3 loadedPos = JsonUtility.FromJson<Vector3>(json); transform.position = loadedPos;实际输出格式：
{ "x": 3.14, "y": 2.71, "z": 1.62 }2.2 枚举的智能处理方案
默认情况下，枚举会被存储为数字值：
public enum CharacterClass { Warrior = 0, Mage = 1, Archer = 2 } // 存档中会存储为数字 {"playerClass": 1}提升可读性的两种方案：
方案1：添加辅助属性
[System.Serializable] public class CharacterData { public CharacterClass classType; // 不序列化的辅助属性 [System.NonSerialized] public string classTypeName; public void BeforeSave() { classTypeName = classType.ToString(); } }方案2：自定义转换器
public static class EnumConverter { public static string ToJson(Enum value) { return $"\"{value.ToString()}\""; } public static T FromJson<T>(string json) where T : Enum { return (T)Enum.Parse(typeof(T), json.Trim('"')); } }2.3 处理字典类型
虽然JsonUtility不支持直接序列化Dictionary，但可以通过中间转换实现：
[System.Serializable] public class SerializableDictionary<K,V> { public List<K> keys = new List<K>(); public List<V> values = new List<V>(); public Dictionary<K,V> ToDictionary() { var dict = new Dictionary<K,V>(); for(int i=0; i<keys.Count; i++) { dict[keys[i]] = values[i]; } return dict; } public static SerializableDictionary<K,V> FromDictionary(Dictionary<K,V> dict) { var serializable = new SerializableDictionary<K,V>(); foreach(var pair in dict) { serializable.keys.Add(pair.Key); serializable.values.Add(pair.Value); } return serializable; } }使用示例：
var originalDict = new Dictionary<string, int>(); var serialized = SerializableDictionary<string,int>.FromDictionary(originalDict); string json = JsonUtility.ToJson(serialized); // 读取时 var loaded = JsonUtility.FromJson<SerializableDictionary<string,int>>(json); var restoredDict = loaded.ToDictionary();3. 实现完整存档流程
3.1 保存游戏状态
完整保存流程应包含这些步骤：
- 收集数据：从各个游戏系统获取当前状态
- 预处理：转换特殊数据类型（如字典）
- 版本标记：注入当前游戏版本号
- 加密处理（可选）：防止玩家手动修改
- 写入磁盘：异步保存避免卡顿
IEnumerator SaveGameCoroutine(string saveSlot) { // 1. 收集数据 GameSaveData saveData = new GameSaveData(); saveData.playerPosition = player.transform.position; saveData.currentState = player.currentState; // 2. 处理特殊类型 saveData.unlockedAchievements = SerializableDictionary<string,bool>.FromDictionary(achievementSystem.unlocked); // 3. 版本控制 saveData.saveVersion = GameVersion.Current; // 4. 转换为JSON string json = JsonUtility.ToJson(saveData, true); // 5. 加密（简单示例） byte[] encrypted = System.Text.Encoding.UTF8.GetBytes(json).Reverse().ToArray(); // 6. 异步保存 string savePath = Path.Combine(Application.persistentDataPath, saveSlot + ".sav"); yield return File.WriteAllBytesAsync(savePath, encrypted); Debug.Log($"游戏已保存到 {savePath}"); }3.2 加载游戏状态
加载时需要考虑更多边界情况：
public bool LoadGame(string saveSlot) { string savePath = Path.Combine(Application.persistentDataPath, saveSlot + ".sav"); if(!File.Exists(savePath)) { Debug.LogWarning("存档文件不存在"); return false; } try { // 1. 读取文件 byte[] encrypted = File.ReadAllBytes(savePath); // 2. 解密（与加密对应） byte[] decrypted = encrypted.Reverse().ToArray(); string json = System.Text.Encoding.UTF8.GetString(decrypted); // 3. 反序列化 GameSaveData saveData = JsonUtility.FromJson<GameSaveData>(json); // 4. 版本检查 if(!IsVersionCompatible(saveData.saveVersion)) { Debug.LogWarning($"存档版本 {saveData.saveVersion} 不兼容"); return false; } // 5. 恢复游戏状态 player.transform.position = saveData.playerPosition; player.currentState = saveData.currentState; // 6. 处理特殊类型 achievementSystem.unlocked = saveData.unlockedAchievements.ToDictionary(); return true; } catch(System.Exception e) { Debug.LogError($"加载存档失败: {e.Message}"); return false; } }3.3 存档版本迁移
当游戏更新后，旧版存档可能需要转换：
bool IsVersionCompatible(string saveVersion) { Version current = new Version(GameVersion.Current); Version saveVer = new Version(saveVersion); // 主版本号不同视为不兼容 if(current.Major != saveVer.Major) return false; // 次版本号较小需要迁移 if(current.Minor > saveVer.Minor) { MigrateSaveData(saveVer); } return true; } void MigrateSaveData(Version oldVersion) { // 示例：v1.1到v1.2的迁移逻辑 if(oldVersion.Minor == 1 && current.Minor == 2) { // 添加新字段的默认值 if(saveData.newField == null) { saveData.newField = defaultValue; } } }4. 高级技巧与优化
4.1 增量存档策略
频繁全量保存可能影响性能，可以考虑：
- 分块保存：将不同系统数据分开存储
- 差异保存：只存储发生变化的部分
- 定时保存：结合自动保存和手动保存
// 差异保存示例 public class DeltaSaveSystem { private GameSaveData lastFullSave; public string GetDeltaSave() { GameSaveData current = GetCurrentState(); GameSaveData delta = new GameSaveData(); // 只记录变化的字段 if(current.playerPosition != lastFullSave.playerPosition) { delta.playerPosition = current.playerPosition; } // ...其他字段比较 return JsonUtility.ToJson(delta); } }4.2 存档压缩与加密
对于大型存档文件：
// 简单压缩示例 byte[] Compress(string json) { byte[] data = Encoding.UTF8.GetBytes(json); using(var output = new MemoryStream()) { using(var gzip = new GZipStream(output, CompressionMode.Compress)) { gzip.Write(data, 0, data.Length); } return output.ToArray(); } } // AES加密示例 byte[] Encrypt(byte[] data, string key) { using(Aes aes = Aes.Create()) { aes.Key = Encoding.UTF8.GetBytes(key); aes.IV = new byte[16]; // 初始化向量 using(var encryptor = aes.CreateEncryptor()) using(var ms = new MemoryStream()) using(var cs = new CryptoStream(ms, encryptor, CryptoStreamMode.Write)) { cs.Write(data, 0, data.Length); cs.FlushFinalBlock(); return ms.ToArray(); } } }4.3 多线程保存方案
为避免保存时的卡顿：
public class AsyncSaveManager : MonoBehaviour { private Thread saveThread; private bool isSaving; public void RequestSave(GameSaveData data) { if(isSaving) return; isSaving = true; saveThread = new Thread(() => { string json = JsonUtility.ToJson(data); byte[] compressed = Compress(json); File.WriteAllBytes(savePath, compressed); isSaving = false; }); saveThread.Start(); } void OnDestroy() { saveThread?.Abort(); } }注意：Unity API不能在子线程调用，需在主线程准备所有数据
5. 实战：RPG游戏存档系统
让我们以一个典型RPG游戏为例，实现完整的多系统存档：
5.1 角色数据保存
[System.Serializable] public class PlayerSaveData { public string characterName; public Vector3 position; public Quaternion rotation; public int currentHealth; public int maxHealth; public int level; public float experience; public Equipment[] equippedItems; } // 装备数据 [System.Serializable] public class Equipment { public string itemId; public EquipmentSlot slot; // 枚举 public int durability; } public enum EquipmentSlot { Head, Chest, Legs, Weapon, Shield }5.2 任务系统存档
[System.Serializable] public class QuestSaveData { public string questId; public QuestStatus status; public int currentStep; public SerializableDictionary<string, int> objectivesProgress; } public enum QuestStatus { NotStarted, InProgress, Completed, Failed }5.3 世界状态保存
[System.Serializable] public class WorldSaveData { public string sceneName; public bool[] switchStates; // 场景中的开关状态 public SerializableDictionary<string, bool> npcDialogueFlags; public SerializableDictionary<string, Vector3> movableObjectPositions; }5.4 完整存档流程示例
public void SaveFullGame() { // 创建存档容器 FullGameSave fullSave = new FullGameSave(); // 收集各系统数据 fullSave.player = playerSystem.GetSaveData(); fullSave.quests = questSystem.GetSaveData(); fullSave.world = worldSystem.GetSaveData(); fullSave.inventory = inventorySystem.GetSaveData(); // 添加元数据 fullSave.saveTime = System.DateTime.Now; fullSave.gameVersion = Application.version; // 转换为JSON string json = JsonUtility.ToJson(fullSave, true); // 压缩加密 byte[] compressed = Compress(json); byte[] encrypted = Encrypt(compressed, encryptionKey); // 写入文件 string savePath = GetSavePath("autosave"); File.WriteAllBytes(savePath, encrypted); Debug.Log($"全系统存档完成，大小：{encrypted.Length/1024}KB"); }在项目中实际使用这套系统后，发现最需要关注的是版本兼容性设计。我们曾遇到一次重大更新导致旧存档无法读取的问题，后来通过添加版本迁移系统彻底解决了这类问题。建议在开发初期就考虑好版本控制策略，为每个存档添加明确的版本标识。
