首页/资讯中心/详情

Unity3D中LitJson-0.16.0集合序列化实战：从原理到库存系统实现

Unity3D中LitJson-0.16.0集合序列化实战：从原理到库存系统实现
📅 发布时间：2026/8/4 7:56:30

1. 项目概述：为什么Unity3D开发者需要LitJson-0.16.0来处理集合序列化？

在Unity3D项目开发中，数据交换是家常便饭。无论是从服务器拉取配置表、保存本地游戏存档，还是不同模块间的数据传递，JSON格式几乎成了首选。Unity自带的JsonUtility虽然方便，但它在处理复杂数据结构，尤其是集合（如List<T>、Dictionary<K, V>）和自定义类时，常常表现得力不从心。这时，一个轻量、高效且与Unity兼容性好的第三方JSON库就显得至关重要。LitJson-0.16.0正是这样一个在Unity社区里经久不衰的“老兵”。

我最初接触LitJson，就是因为被JsonUtility在序列化一个包含List<Item>的玩家背包类时给“坑”了。它要么直接忽略掉集合，要么在反序列化时得到一个空列表，调试起来非常头疼。而LitJson-0.16.0版本，作为其发展历程中一个稳定且功能相对完善的节点，对C#的集合类型有着原生且可靠的支持。它不仅仅是一个“能用”的工具，更是一个能让你在数据层设计上更加自由、减少样板代码的利器。对于需要处理复杂游戏数据（如技能树、对话系统、装备合成表）的开发者来说，掌握LitJson对集合的序列化与反序列化，是提升开发效率和代码健壮性的基本功。

简单来说，这个“项目”的核心就是：在Unity3D中，集成并使用LitJson-0.16.0库，以正确、高效地完成对各类C#集合对象的JSON序列化与反序列化操作，规避Unity原生方案的局限性。无论你是独立开发者还是团队协作，这都是一项能让你在数据持久化和网络通信中游刃有余的必备技能。

2. LitJson-0.16.0核心特性与集成方案解析

在深入集合序列化之前，我们有必要先搞清楚LitJson-0.16.0这个工具本身。为什么是0.16.0这个版本？它和更新版本或者Unity的JsonUtility、Newtonsoft.Json（现为Json.NET）相比有什么不同？理解了这些，你才能做出最合适的技术选型。

2.1 版本选择与特性定位

LitJson是一个用C#编写的轻量级JSON库，其设计目标就是快速和易于使用。0.16.0版本是一个在功能和稳定性上取得很好平衡的经典版本。相较于更早的版本，它修复了许多bug，并增强了对泛型集合的支持；而相较于一些更新的版本（虽然LitJson本身更新并不频繁），0.16.0足够稳定，网上资料和解决方案也最丰富，避免了使用最新版可能遇到的未知兼容性问题。

它的核心优势在于：

  1. 轻量级：单个LitJson.dll文件，体积小巧，不会明显增加项目构建大小。
  2. 零依赖：除了.NET或Unity的运行时库，它不依赖任何其他第三方库，集成简单。
  3. 良好的集合支持：这是相对于JsonUtility最大的优势。它能正确处理List<T>,Dictionary<K, V>, 数组等。
  4. 与Unity的亲和性：在Unity的脚本执行顺序和AOT编译环境下工作良好。

与Newtonsoft.Json对比，LitJson功能上要简单得多。Newtonsoft.Json功能极其强大，定制化程度极高，但相应地也更重，在移动平台可能会对IL2CPP代码裁剪和性能产生一些影响。对于绝大多数Unity游戏的数据序列化需求，LitJson-0.16.0的功能已经绰绰有余，属于“刚好够用”的甜点区。

2.2 多种集成方式与实操要点

将LitJson-0.16.0集成到Unity项目中有几种常见方式，每种都有其适用场景。

方式一：直接导入DLL（最推荐）这是最干净、最直接的方式。你可以从其GitHub仓库的Release中下载编译好的LitJson.dll，或者从其他包含此版本的项目中获取。

  1. 在Unity项目的Assets文件夹下，创建一个名为Plugins的文件夹（如果不存在）。这是Unity识别托管插件DLL的标准位置。
  2. 将LitJson.dll文件拖入Plugins文件夹。
  3. 在任意C#脚本中，添加using LitJson;命名空间，即可开始使用。

注意：确保你获取的DLL是适用于.NET Standard 2.0或.NET Framework对应版本的，以兼容Unity的运行时。通常为LitJson编译的DLL都能很好地工作。

方式二：导入源码（便于调试和微调）你也可以将LitJson的整个C#源代码文件夹（通常包含JsonData.cs,JsonMapper.cs等）复制到你的Assets/Scripts目录下的某个文件夹中。这样做的好处是，你可以在Unity中直接断点调试LitJson的内部逻辑，或者在极端情况下对源码进行微调。缺点是可能会稍微增加项目编译时间，并且需要自行管理源码版本。

方式三：通过Unity Package Manager或Asset Store（不常见）一些资源包或框架可能会将LitJson作为依赖打包。但直接获取纯LitJson库，前两种方式更可控。

我个人强烈推荐方式一。它分离了依赖和业务逻辑，项目结构清晰，也符合第三方库的管理惯例。集成后，你可以在代码中通过JsonMapper.ToJson()和JsonMapper.ToObject()这两个核心方法进行序列化和反序列化，接下来我们就聚焦于集合操作。

3. 核心集合类型的序列化与反序列化实战

集合是数据结构的骨架。在游戏中，角色技能列表、背包物品数组、关卡配置字典，无一不是集合。LitJson处理这些类型的基本原理是：通过反射分析对象的类型信息，将公有字段和属性（具有getter和setter）转换为JSON的键值对。对于集合，它会递归地处理其中的每个元素。

3.1 列表与数组的序列化

列表(List<T>)和数组(T[])在JSON中都被表示为数组（方括号[]包围的结构）。LitJson对它们的支持非常直接。

using LitJson; using System.Collections.Generic; [System.Serializable] // 这个特性对于LitJson不是必须的，但保留它是一个好习惯。 public class PlayerData { public string PlayerName; public int Level; public List<string> CompletedMissions; // 字符串列表 public List<Equipment> Equipments; // 自定义对象列表 } [System.Serializable] public class Equipment { public int Id; public string Name; } // 序列化示例 PlayerData player = new PlayerData(); player.PlayerName = "Hero"; player.Level = 10; player.CompletedMissions = new List<string> { "Mission1", "Mission3", "BossRush" }; player.Equipments = new List<Equipment> { new Equipment { Id = 101, Name = "Iron Sword" }, new Equipment { Id = 205, Name = "Wooden Shield" } }; string json = JsonMapper.ToJson(player); Debug.Log(json);

上述代码输出的JSON大致如下：

{ "PlayerName": "Hero", "Level": 10, "CompletedMissions": ["Mission1", "Mission3", "BossRush"], "Equipments": [ {"Id": 101, "Name": "Iron Sword"}, {"Id": 205, "Name": "Wooden Shield"} ] }

反序列化同样简单：

string jsonString = @"{ 'PlayerName': 'Hero', 'Level': 10, 'CompletedMissions': ['Mission1', 'Mission3', 'BossRush'], 'Equipments': [{'Id': 101, 'Name': 'Iron Sword'}, {'Id': 205, 'Name': 'Wooden Shield'}] }"; // 注意：JSON字符串中可以使用单引号，LitJson能识别。 PlayerData loadedPlayer = JsonMapper.ToObject<PlayerData>(jsonString); Debug.Log(loadedPlayer.Equipments[0].Name); // 输出：Iron Sword

实操心得：

  • 对于数组，操作方式与List<T>完全一致。LitJson在反序列化时会自动创建适当大小的数组。
  • 确保集合中的元素类型（T）本身也是可以被LitJson序列化的。基本类型（int,float,string,bool）和包含基本类型或可序列化对象的自定义类都没问题。

3.2 字典的序列化与关键陷阱

字典(Dictionary<K, V>)的序列化是重点，也是容易踩坑的地方。在JSON中，字典被自然地表示为对象（花括号{}包围的键值对集合）。

public class GameConfig { public Dictionary<string, int> LevelExpRequirement; // 键为关卡名，值为所需经验 public Dictionary<int, string> ItemNameMap; // 键为物品ID，值为物品名 } GameConfig config = new GameConfig(); config.LevelExpRequirement = new Dictionary<string, int> { {"Level1", 100}, {"Level2", 300}, {"Level5", 1200} }; config.ItemNameMap = new Dictionary<int, string> { {101, "Health Potion"}, {205, "Magic Crystal"} }; string configJson = JsonMapper.ToJson(config); Debug.Log(configJson);

输出：

{ "LevelExpRequirement": { "Level1": 100, "Level2": 300, "Level5": 1200 }, "ItemNameMap": { "101": "Health Potion", // 注意：键被转换为字符串“101” "205": "Magic Crystal" } }

这里有一个至关重要的陷阱：JSON规范要求对象的键必须是字符串。因此，当你的字典键类型是int、enum或其他非字符串类型时，LitJson在序列化时会调用它们的ToString()方法将其转换为字符串。在反序列化时，它需要将这些字符串键再转换回原始类型。

反序列化字典：

string dictJson = @"{'101': 'Health Potion', '205': 'Magic Crystal'}"; Dictionary<int, string> loadedDict = JsonMapper.ToObject<Dictionary<int, string>>(dictJson); // 成功：loadedDict 包含键 101 和 205。

重要警告：这个转换过程依赖于LitJson内部的类型转换器。对于int、float等基本类型，转换通常很稳定。但是，对于自定义类型作为字典键，情况就复杂了。如果自定义类没有正确重写ToString()和提供相应的从字符串解析的方法，反序列化很可能会失败，或者导致字典行为异常。因此，在项目实践中，强烈建议字典的键使用string类型，这样可以避免绝大多数麻烦。如果必须用其他类型，请务必进行充分的测试。

3.3 嵌套集合与复杂数据结构的处理

游戏数据往往是树状或图状结构，嵌套集合非常常见。例如，一个公会信息包含成员列表，每个成员又有自己的成就列表。

public class Achievement { public string Id; public string Name; } public class GuildMember { public string Name; public List<Achievement> Achievements; } public class Guild { public string GuildName; public List<GuildMember> Members; } Guild myGuild = new Guild { GuildName = "Dragon Slayers", Members = new List<GuildMember> { new GuildMember { Name = "Arthur", Achievements = new List<Achievement> { new Achievement { Id = "ACH_01", Name = "First Kill" }, new Achievement { Id = "ACH_05", Name = "Dragon Hunter" } } }, new GuildMember { Name = "Lancelot", Achievements = new List<Achievement> { new Achievement { Id = "ACH_03", Name = "PvP Champion" } } } } }; string guildJson = JsonMapper.ToJson(myGuild); // LitJson 会递归地处理所有嵌套对象和集合，生成结构完整的JSON。

LitJson处理这类嵌套结构的能力很强，只要每一层的类型都是可序列化的，它就能生成层次分明的JSON数据。反序列化时，它也能正确地重建整个对象树。

注意事项：

  • 循环引用：如果对象之间存在循环引用（例如，Player对象有一个Party引用，而Party对象又包含一个List<Player>），LitJson在序列化时会陷入无限递归导致堆栈溢出。这是大多数简单JSON库的通病。在设计数据结构时，应避免循环引用，或者使用ID引用代替直接对象引用。
  • 性能考虑：深度嵌套的复杂对象进行频繁的序列化/反序列化可能成为性能瓶颈，尤其是在移动设备上。对于不变的核心配置数据，可以序列化一次并缓存结果。对于频繁变动的数据，要考虑数据量的大小。

4. 高级定制与疑难问题排查指南

掌握了基本操作后，你可能会遇到一些特殊需求或棘手问题。LitJson-0.16.0提供了一些机制来进行定制，同时也存在一些需要绕行的“坑”。

4.1 自定义序列化行为与属性排除

默认情况下，LitJson会序列化所有公有字段和具有getter/setter的属性。但有时我们想排除某些敏感或临时字段（如缓存数据、运行时状态），或者对序列化过程进行自定义。

方法一：使用[JsonIgnore]特性这是最简洁的方式。为字段或属性标记[JsonIgnore]，LitJson就会在序列化和反序列化时忽略它。

using LitJson; public class SaveData { public string UserId; public string Token; [JsonIgnore] // 这个字段不会被序列化到JSON中 public DateTime LastLoginTimeCache; public List<int> UnlockedLevels; }

方法二：实现IJsonWrapper接口（高级）如果你需要对一个复杂类型的序列化过程进行完全控制，可以实现IJsonWrapper接口。这让你可以手动决定如何将对象转换为JsonData（LitJson的内部表示），以及如何从JsonData重建对象。这种方法较为复杂，通常只在处理特殊第三方库类型或需要非常规映射时才使用。

方法三：使用JsonMapper的注册类型转换器你可以通过JsonMapper.RegisterExporter和JsonMapper.RegisterImporter来为特定类型注册自定义的导出（序列化）和导入（反序列化）逻辑。例如，Unity的Vector3类型默认无法被LitJson直接序列化，你可以为其注册转换器：

// 注册Vector3的导出器 JsonMapper.RegisterExporter<Vector3>((v, writer) => { writer.WriteObjectStart(); writer.WritePropertyName("x"); writer.Write(v.x); writer.WritePropertyName("y"); writer.Write(v.y); writer.WritePropertyName("z"); writer.Write(v.z); writer.WriteObjectEnd(); }); // 注册Vector3的导入器 JsonMapper.RegisterImporter<double, float>(input => (float)input); // 可能需要先注册double到float的转换 // 注意：为Vector3注册一个完整的导入器稍微复杂，需要从JsonData对象解析，这里是一个简化示例思路。

通过这种方式，当你序列化一个包含Vector3的对象时，它会输出为{"x":1.0, "y":2.0, "z":3.0}的格式。

4.2 常见问题排查与解决方案实录

在实际项目中，你肯定会遇到一些报错或非预期行为。下面是我踩过的一些坑和解决方案。

问题一：反序列化后集合为null或空。

  • 可能原因1：JSON字符串中的键名与C#类中的字段/属性名大小写不匹配。LitJson默认是大小写敏感的。
    • 解决方案：确保JSON键名与C#字段名完全一致。或者，在反序列化前，使用JsonMapper.ToObject的重载版本，传入一个JsonReader并设置其属性，但0.16.0版本对大小写转换的支持较弱。更稳妥的做法是统一命名规范（如都用驼峰式）。
  • 可能原因2：类没有无参构造函数。LitJson在反序列化时需要调用无参构造函数来创建对象实例。
    • 解决方案：为你的数据类添加一个公共的无参构造函数。
  • 可能原因3：集合字段本身在JSON中不存在或为null。
    • 解决方案：检查你的JSON数据源是否完整。可以在类定义中为集合字段赋予一个空的初始值（如public List<string> Items = new List<string>();），这样即使JSON中没有对应字段，反序列化后也会得到一个空列表而非null。

问题二：序列化/反序列化时抛出类型转换异常。

  • 可能原因：JSON中的数据类型与C#字段类型不兼容。例如，JSON中某个值是字符串"100"，但C#字段是int类型。
    • 解决方案：LitJson会尝试进行基本类型间的转换（如字符串转数字）。如果失败，需要检查数据源的正确性。对于自定义类型，确保其字段类型匹配。

问题三：字典反序列化失败，尤其是键为枚举类型时。

  • 可能原因：如前所述，字典键在JSON中必须是字符串。如果键是枚举，LitJson会使用枚举值的名称（字符串形式）作为键。反序列化时，它需要将字符串转换回枚举值。
    • 解决方案：为枚举类型注册一个导入器，或者更简单的方法，在代码中使用字符串作为字典键，在逻辑层再将字符串转换为枚举。这是最保险的做法。
    // 不推荐（易出错）： // public Dictionary<WeaponType, int> WeaponCount; // 推荐： public Dictionary<string, int> WeaponCount; // 键存为 "Sword", "Axe"

问题四：性能问题，序列化大量数据时卡顿。

  • 可能原因：对非常大的对象树进行频繁的完整序列化。
    • 解决方案：
      1. 增量更新：只序列化发生变化的部分数据，而不是整个对象。
      2. 缓存结果：对于不常变化的数据（如配置表），序列化一次后将JSON字符串缓存起来。
      3. 评估需求：是否真的需要将整个复杂对象序列化？有时只传递一个ID或最小数据集更高效。
      4. 考虑替代方案：如果数据量极大且性能要求苛刻，可以评估MemoryPack、MessagePack等二进制序列化方案，它们速度更快，体积更小，但可读性差。

4.3 与Unity工作流的结合：ScriptableObject与预制体

在Unity中，ScriptableObject是存储游戏数据（如物品、技能、关卡配置）的绝佳工具。我们可以结合LitJson，实现ScriptableObject数据的导入导出，便于策划配置和版本管理。

  1. 从JSON文件加载数据到ScriptableObject：
    // 在Editor脚本中 using UnityEditor; using LitJson; public class DataImporter : EditorWindow { [MenuItem("Tools/Load JSON to SO")] static void LoadJsonToScriptableObject() { string jsonPath = EditorUtility.OpenFilePanel("Select JSON file", "", "json"); if (!string.IsNullOrEmpty(jsonPath)) { string jsonContent = File.ReadAllText(jsonPath); ItemListData itemData = JsonMapper.ToObject<ItemListData>(jsonContent); // 假设ItemListData是一个ScriptableObject类，包含List<Item> var so = ScriptableObject.CreateInstance<ItemListData>(); so.items = itemData.items; // 赋值 string assetPath = "Assets/Resources/ItemData.asset"; AssetDatabase.CreateAsset(so, assetPath); AssetDatabase.SaveAssets(); EditorUtility.DisplayDialog("Success", "Data loaded and saved to SO!", "OK"); } } }
  2. 将ScriptableObject数据导出为JSON：反向操作即可，读取SO中的数据，用JsonMapper.ToJson()转换为字符串，再保存为文本文件。

这种做法分离了数据配置（JSON文件，可由策划在Excel导出后获得）和运行时数据（ScriptableObject，Unity可高效加载），是中型以上项目常用的数据管理模式。

5. 实战案例：构建一个可持久化的游戏库存系统

让我们通过一个综合案例，将上述所有知识点串联起来。我们将构建一个简单的玩家库存系统，支持物品的添加、移除、保存到本地和从本地加载。

5.1 系统设计与数据模型定义

首先，定义核心数据类。我们将使用Dictionary来存储物品ID和数量的映射，因为查找和更新效率高。

// InventoryItem.cs - 基础物品定义（可创建为ScriptableObject） [CreateAssetMenu(fileName = "New Item", menuName = "Inventory/Item")] public class InventoryItem : ScriptableObject { public string itemId; // 唯一标识符，用作字典键 public string displayName; public Sprite icon; // ... 其他属性如描述、类型、使用效果等 } // InventorySaveData.cs - 纯数据类，用于序列化 [System.Serializable] public class InventorySaveData { // 键：物品ID， 值：物品数量 public Dictionary<string, int> itemQuantityMap = new Dictionary<string, int>(); public int currencyGold; public DateTime lastSaveTime; // 注意：DateTime需要特殊处理 } // InventoryManager.cs - 单例管理器，负责库存逻辑和持久化 public class InventoryManager : MonoBehaviour { public static InventoryManager Instance { get; private set; } private InventorySaveData currentSaveData; private string saveFilePath; void Awake() { if (Instance == null) { Instance = this; DontDestroyOnLoad(gameObject); saveFilePath = Path.Combine(Application.persistentDataPath, "inventory_save.json"); LoadInventory(); } else { Destroy(gameObject); } } }

5.2 核心序列化与反序列化实现

在InventoryManager中实现加载和保存方法。这里需要处理DateTime的序列化问题，因为LitJson默认不支持。

public void SaveInventory() { if (currentSaveData == null) return; // 注册DateTime的转换器（简易版，转换为ISO8601字符串） if (!JsonMapper.IsTypeRegistered(typeof(DateTime))) { JsonMapper.RegisterExporter<DateTime>((dt, writer) => writer.Write(dt.ToString("o"))); // "o" 是ISO8601格式 JsonMapper.RegisterImporter<string, DateTime>(input => DateTime.Parse(input)); } currentSaveData.lastSaveTime = DateTime.Now; string json = JsonMapper.ToJson(currentSaveData); try { File.WriteAllText(saveFilePath, json); Debug.Log($"Inventory saved to: {saveFilePath}"); } catch (System.Exception e) { Debug.LogError($"Failed to save inventory: {e.Message}"); } } public void LoadInventory() { if (!File.Exists(saveFilePath)) { currentSaveData = new InventorySaveData(); Debug.Log("No save file found, creating new inventory."); return; } try { string json = File.ReadAllText(saveFilePath); // 同样需要确保DateTime转换器已注册 if (!JsonMapper.IsTypeRegistered(typeof(DateTime))) { JsonMapper.RegisterImporter<string, DateTime>(input => DateTime.Parse(input)); } currentSaveData = JsonMapper.ToObject<InventorySaveData>(json); if (currentSaveData.itemQuantityMap == null) { currentSaveData.itemQuantityMap = new Dictionary<string, int>(); } Debug.Log($"Inventory loaded. Gold: {currentSaveData.currencyGold}, Items: {currentSaveData.itemQuantityMap.Count}"); } catch (System.Exception e) { Debug.LogError($"Failed to load inventory: {e.Message}. Creating new one."); currentSaveData = new InventorySaveData(); } }

5.3 业务逻辑封装与测试

添加操作库存的方法，并确保任何修改后自动调用保存（或提供手动保存按钮）。

public bool AddItem(string itemId, int quantity = 1) { if (string.IsNullOrEmpty(itemId) || quantity <= 0) return false; if (currentSaveData.itemQuantityMap.ContainsKey(itemId)) { currentSaveData.itemQuantityMap[itemId] += quantity; } else { currentSaveData.itemQuantityMap[itemId] = quantity; } SaveInventory(); // 自动保存 return true; } public bool RemoveItem(string itemId, int quantity = 1) { if (!currentSaveData.itemQuantityMap.ContainsKey(itemId)) return false; int currentQty = currentSaveData.itemQuantityMap[itemId]; if (currentQty < quantity) return false; currentQty -= quantity; if (currentQty == 0) { currentSaveData.itemQuantityMap.Remove(itemId); } else { currentSaveData.itemQuantityMap[itemId] = currentQty; } SaveInventory(); // 自动保存 return true; } public int GetItemQuantity(string itemId) { if (currentSaveData.itemQuantityMap.TryGetValue(itemId, out int qty)) { return qty; } return 0; }

测试与验证： 在Unity编辑器中，创建一个空场景，挂载InventoryManager。然后可以写一个简单的测试脚本，在Start中调用AddItem("potion_health", 5)和AddItem("sword_iron", 1)。运行游戏后，去Application.persistentDataPath目录（可以在Unity Editor中通过Debug.Log(Application.persistentDataPath)查看路径）找到生成的inventory_save.json文件。用文本编辑器打开，你应该能看到类似以下的结构：

{ "itemQuantityMap": { "potion_health": 5, "sword_iron": 1 }, "currencyGold": 0, "lastSaveTime": "2023-10-27T10:30:00.1234567Z" }

停止运行，再次启动游戏，LoadInventory方法会读取这个文件，并恢复你的物品数据。这就实现了一个完整的、基于LitJson和本地JSON文件的库存持久化系统。

这个案例展示了从数据模型设计、LitJson集成、特殊类型处理到完整业务逻辑的闭环。你可以在此基础上扩展更多功能，如按物品类型分类、背包容量限制、装备栏位等。关键在于，所有复杂的数据结构变化，最终都能通过LitJson可靠地转化为可存储、可传输的JSON字符串。