用JsonUtility在Unity里做个简易存档系统：5分钟搞定角色位置和状态保存
用JsonUtility在Unity中构建轻量级存档系统的实战指南
刚接触Unity开发的程序员常常会遇到一个现实问题：如何快速保存游戏进度？你可能尝试过PlayerPrefs存储简单数值，但当需要记录角色位置、装备列表等复杂数据时，这种方案就显得力不从心。实际上，Unity内置的JsonUtility配合C#的序列化特性，能在不引入第三方库的情况下，优雅地解决结构化数据存储问题。
今天我们就从一个具体场景出发：为平台跳跃游戏的主角实现存档功能。需要保存的角色数据包括：
- 三维空间中的位置坐标（Vector3）
- 当前生命值和最大生命值（int）
- 已收集的关键物品ID列表（List ）
1. 设计可序列化的数据结构
在动手编码前，首先要规划数据的组织方式。JsonUtility对数据结构有明确要求，我们需要创建专门的存档类：
[System.Serializable] public class CharacterSaveData { public Vector3 position; public int currentHealth; public int maxHealth; public List<string> collectedItems; }关键设计要点：
- 必须添加
[Serializable]特性 - 所有需要保存的字段必须是public或标注
[SerializeField] - 避免使用Dictionary等不支持的集合类型
注意：虽然属性（get/set）在C#中很常见，但JsonUtility目前仅支持字段序列化
2. 实现核心存档与读档功能
接下来创建存档管理器组件，挂载到场景中的空对象上：
using UnityEngine; using System.IO; public class SaveSystem : MonoBehaviour { private string savePath; void Awake() { savePath = Path.Combine(Application.persistentDataPath, "character_save.json"); } public void SaveCharacter(GameObject player) { CharacterSaveData data = new CharacterSaveData(); data.position = player.transform.position; CharacterStats stats = player.GetComponent<CharacterStats>(); data.currentHealth = stats.CurrentHealth; data.maxHealth = stats.MaxHealth; data.collectedItems = stats.GetCollectedItems(); string json = JsonUtility.ToJson(data, true); File.WriteAllText(savePath, json); Debug.Log($"存档成功：{savePath}"); } public void LoadCharacter(GameObject player) { if (!File.Exists(savePath)) return; string json = File.ReadAllText(savePath); CharacterSaveData data = JsonUtility.FromJson<CharacterSaveData>(json); player.transform.position = data.position; CharacterStats stats = player.GetComponent<CharacterStats>(); stats.InitializeHealth(data.currentHealth, data.maxHealth); stats.RestoreCollectedItems(data.collectedItems); } }代码解析：
Application.persistentDataPath获取各平台安全的存储路径ToJson的第二个参数设置为true，生成格式化的JSON便于调试- 实际项目中应考虑添加异常处理
3. 处理Unity特殊数据类型
JsonUtility对Unity原生类型的支持是其最大优势之一。当序列化包含Vector3的类时，生成的JSON结构如下：
{ "position": { "x": 1.25, "y": 0.0, "z": -3.8 }, "currentHealth": 80, "maxHealth": 100, "collectedItems": ["key_01", "potion_03"] }支持的Unity特有类型包括：
| 数据类型 | JSON表现形式 | 注意事项 |
|---|---|---|
| Vector2/3 | 嵌套x/y/z对象 | 直接支持 |
| Quaternion | 四元数字段 | 旋转数据存储更高效 |
| Color | RGBA值 | 需注意颜色空间 |
| Rect | 位置尺寸组合 | 常用于UI系统 |
4. 进阶技巧与性能优化
当系统需要频繁存取时，可以考虑以下优化策略：
内存缓存策略：
private CharacterSaveData _cachedData; public void QuickSave() { if (_cachedData == null) return; File.WriteAllText(savePath, JsonUtility.ToJson(_cachedData)); }二进制加密方案：
using System.Security.Cryptography; string EncryptJson(string json) { byte[] bytes = System.Text.Encoding.UTF8.GetBytes(json); using Aes aes = Aes.Create(); // 配置加密密钥和IV... byte[] encrypted = aes.TransformFinalBlock(bytes, 0, bytes.Length); return Convert.ToBase64String(encrypted); }存档版本控制：
[System.Serializable] public class SaveMetadata { public int version = 1; public long timestamp; // 其他元信息... } public string CreateVersionedSave(CharacterSaveData data) { SaveMetadata meta = new SaveMetadata { timestamp = System.DateTime.Now.Ticks }; string dataJson = JsonUtility.ToJson(data); string metaJson = JsonUtility.ToJson(meta); return $"{{ \"meta\": {metaJson}, \"data\": {dataJson} }}"; }5. 实际应用中的问题排查
即使按照规范编写代码，仍可能遇到一些典型问题：
常见问题排查表：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 字段值为空 | 未标记[Serializable] | 检查类声明 |
| 部分数据未保存 | 字段非public | 改为public或添加[SerializeField] |
| JSON解析失败 | 文件损坏 | 添加完整性校验 |
| 移动端读取异常 | 路径权限问题 | 使用Application.persistentDataPath |
调试时可以添加日志验证：
Debug.Log($"原始数据：{JsonUtility.ToJson(data, true)}"); Debug.Log($"存储路径：{savePath}"); Debug.Log($"文件存在：{File.Exists(savePath)}");在最近的一个2D平台游戏项目中，这套存档系统成功支持了以下复杂需求：
- 多存档槽位管理
- 自动存档和手动存档并存
- 存档截图缩略图生成
- 跨场景状态保持
实现过程中最大的收获是：保持数据结构简单明确，比过度设计复杂的继承体系更有利于长期维护。当需要扩展时，可以通过组合而非继承来增加新功能。