1. 项目概述为什么Unity开发者绕不开JSON解析如果你在Unity里做过数据管理、配置读取或者网络通信那你肯定跟JSON打过交道。这玩意儿现在几乎是数据交换的“世界语”从游戏存档、关卡配置到从服务器拉取排行榜、道具列表再到和第三方API对接JSON的身影无处不在。但Unity本身对JSON的支持怎么说呢有点“基础”。自带的JsonUtility用起来是快但限制也多稍微复杂点的数据结构或者需要点灵活性的场景它就有点力不从心了。所以我们这些Unity老鸟的日常工具箱里总会备着几款第三方的JSON解析工具。它们各有各的脾气和擅长领域选对了工具开发效率能提升一大截选错了或者用错了可能就是无尽的调试和性能瓶颈。今天我就结合自己这些年踩过的坑和积累的经验给你掰扯掰扯Unity里最常用、也最值得推荐的三大JSON工具Unity原生的JsonUtility、功能强大的Newtonsoft.Json也就是Json.NET以及后起之秀System.Text.Json。我会告诉你它们各自适合什么场景怎么用以及那些官方文档里不会写的“坑”和技巧。2. 三大工具核心特性与选型指南面对一个JSON解析需求别急着写代码先花两分钟想想该用哪个工具。选型不对努力白费。下面这张表能帮你快速抓住核心区别特性维度Unity JsonUtilityNewtonsoft.Json (Json.NET)System.Text.Json来源与集成Unity引擎原生无需额外导入第三方库需通过Package Manager或手动导入.NET Core 3.0 原生Unity 2021.2 部分支持序列化/反序列化速度极快针对简单结构优化中等偏慢功能丰富导致开销快设计目标就是高性能功能丰富度极简仅支持基础功能极其丰富高度可定制较丰富平衡性能与功能对Unity类型支持原生完美支持如Vector3, Color需自定义转换器Converter需自定义转换器Converter复杂数据支持弱不支持字典、多态、私有字段等强全支持高度灵活中等部分支持需配置推荐使用场景1. 简单的数据类MonoBehaviour序列化2. 性能敏感的简单数据流3. 快速原型验证1. 复杂数据结构含字典、接口、继承2. 需要高度定制化序列化规则3. 与旧有.NET生态库交互1. Unity 2021.2 新项目2. 对性能有要求且结构不太复杂3. 希望使用.NET官方未来主流方案选型心法求快、求简单用JsonUtility如果你的数据类就是一堆public字段没继承、没接口、没字典纯粹为了存个配置或者临时传个数据JsonUtility是不二之选。它的速度优势在移动端高频调用时非常明显。求稳、求功能全用Newtonsoft.Json如果你的项目已经用了它或者数据结构非常复杂比如游戏存档包含各种类型的物品、技能树需要处理多态、忽略某些字段、自定义日期格式等Json.NET依然是“瑞士军刀”社区资源和解决方案也最全。求新、求平衡尝试System.Text.Json如果是全新的Unity 2021.2项目特别是面向较新.NET版本可以考虑用它。它在性能和功能上取得了不错的平衡而且是.NET官方主推的方向未来兼容性和性能优化更有保障。注意System.Text.Json在Unity中的支持是逐步完善的。在较早的Unity版本或特定的.NET Standard版本下某些API可能不可用。使用前最好在目标Unity版本中测试一下核心功能。3. 工具一Unity原生JsonUtility 深度解析与实战JsonUtility是Unity亲儿子集成在UnityEngine命名空间下开箱即用。它的设计哲学是简单和性能为此牺牲了灵活性。3.1 核心API与基础用法它的API简单到令人发指主要就两个静态方法string ToJson(object obj, bool prettyPrint false): 将对象序列化成JSON字符串。T FromJsonT(string json): 将JSON字符串反序列化成指定类型的对象。还有一个FromJsonOverwrite用于将JSON数据反序列化并覆盖到一个已存在对象的公共字段上适合部分更新。基础示例假设我们有一个玩家数据类[System.Serializable] // 这是关键JsonUtility只处理标记为可序列化的类 public class PlayerData { public string playerName; public int level; public float health; // public Vector3 position; // Unity基础类型直接支持 }序列化和反序列化PlayerData player new PlayerData { playerName Hero, level 10, health 85.5f }; // 序列化 string json JsonUtility.ToJson(player, true); // prettyPrint为true输出格式化后的JSON Debug.Log(json); // 输出 // { // playerName: Hero, // level: 10, // health: 85.5 // } // 反序列化 string receivedJson {\playerName\:\Villain\,\level\:99,\health\:100.0}; PlayerData newPlayer JsonUtility.FromJsonPlayerData(receivedJson); Debug.Log(newPlayer.playerName); // 输出: Villain3.2 优势、局限与实战避坑指南优势零依赖性能极致由于是引擎原生且功能单纯在序列化简单POCOPlain Old C# Object时速度远超其他第三方库对移动设备友好。完美支持Unity特有类型Vector2/3/4,Quaternion,Color,Rect,Bounds等类型可以直接序列化/反序列化非常方便。与Unity工作流集成好[System.Serializable]标签同时也是Unity Inspector面板显示的条件一套标签两处使用。局限与“坑”必须使用[Serializable]标签这是最大的限制。类、结构体必须标记此标签且只处理公有字段public fields。属性Properties、私有/受保护字段默认都会被忽略。不支持复杂类型不支持字典Dictionary这是最常遇到的坑。如果你尝试序列化一个Dictionarystring, int它会直接忽略。不支持多态继承反序列化时无法根据JSON内容自动识别并创建派生类对象。不支持接口Interface类型字段。不支持ListListT这类嵌套泛型集合但ListT和数组T[]是支持的。反序列化时构造函数不会被调用对象是通过System.Activator创建的不会走你定义的构造函数。实战避坑技巧应对字典需求如果需要字典结构可以将其包装在一个可序列化的类中用两个List分别存储键和值或者直接使用ListKeyValuePair。虽然麻烦但在性能关键路径上这比引入Newtonsoft.Json更高效。[System.Serializable] public class SerializableDictionaryTKey, TValue { public ListTKey keys new ListTKey(); public ListTValue values new ListTValue(); // 可以添加方法将其转换成真正的Dictionary }处理私有数据如果确实需要序列化私有字段可以将其公开或者使用公共属性配合[SerializeField]标签这样Inspector和JsonUtility都能识别。部分更新对象使用JsonUtility.FromJsonOverwrite可以只更新JSON中提供的字段保留对象原有的其他字段值。这在处理网络增量更新时很有用。4. 工具二功能王者 Newtonsoft.Json (Json.NET) 全方位攻略如果JsonUtility是“水果刀”那Newtonsoft.Json就是“万能工具箱”。它几乎能处理你能想到的任何JSON相关场景但也因此更重。4.1 在Unity中的安装与配置现在最推荐的方式是通过Unity的Package Manager安装打开Window - Package Manager。点击左上角“”号选择“Add package from git URL...”。输入https://github.com/jilleJr/Newtonsoft.Json-for-Unity.git#upm这是一个专门为Unity打包的版本解决了原生Newtonsoft.Json在IL2CPP下可能存在的AOT编译问题。等待安装完成。安装后命名空间为Newtonsoft.Json。4.2 核心功能实战与高级特性基础使用和JsonUtility类似但功能强大得多using Newtonsoft.Json; public class ComplexData { public string Name { get; set; } // 支持属性 private int secretCode; // 默认不支持私有字段但可通过设置支持 public Dictionarystring, object Stats { get; set; } // 支持字典 public IItem EquippedItem { get; set; } // 支持接口但需要配置 } // 序列化 ComplexData data new ComplexData { Name Test, Stats new Dictionarystring, object { { Atk, 100 } } }; string json JsonConvert.SerializeObject(data, Formatting.Indented); // 反序列化 ComplexData newData JsonConvert.DeserializeObjectComplexData(json);高级特性详解自定义序列化设置JsonSerializerSettings这是它的灵魂。JsonSerializerSettings settings new JsonSerializerSettings { NullValueHandling NullValueHandling.Ignore, // 忽略null值 DefaultValueHandling DefaultValueHandling.Ignore, // 忽略类型默认值 ContractResolver new CamelCasePropertyNamesContractResolver(), // 属性名转为驼峰命名 Converters new ListJsonConverter { new StringEnumConverter() }, // 枚举转字符串 TypeNameHandling TypeNameHandling.Auto // 处理多态JSON中会包含类型信息 }; string jsonWithSettings JsonConvert.SerializeObject(data, settings);处理多态继承通过TypeNameHandling设置JSON中会自动添加$type字段记录具体类型反序列化时能正确还原。settings.TypeNameHandling TypeNameHandling.All; // 序列化一个基类引用实际指向派生类对象 BaseClass obj new DerivedClass(); string polyJson JsonConvert.SerializeObject(obj, settings); // 反序列化时能正确得到DerivedClass实例 BaseClass restored JsonConvert.DeserializeObjectBaseClass(polyJson, settings);使用属性标签进行精细控制public class Player { [JsonProperty(player_name)] // 序列化后字段名为player_name public string PlayerName { get; set; } [JsonIgnore] // 完全忽略此属性 public string TemporaryToken { get; set; } [JsonProperty(Required Required.Always)] // 该属性在JSON中必须存在 public int Id { get; set; } }4.3 性能优化与常见问题排查性能优化点重用JsonSerializerSettings不要每次序列化都new一个创建开销不小。应该将其定义为静态只读成员。使用流式API处理大JSON对于非常大的JSON文件使用JsonTextReader和JsonTextWriter进行流式读写避免一次性加载到内存。using (StreamReader file File.OpenText(large.json)) using (JsonTextReader reader new JsonTextReader(file)) { while (reader.Read()) { // 逐Token处理 } }避免过度使用TypeNameHandling它会增加JSON大小并带来轻微性能开销且可能存在安全风险反序列化时可能实例化任意类型仅在必需时使用。常见问题排查循环引用错误对象A引用BB又引用A序列化时会抛出JsonSerializationException。解决方案在设置中ReferenceLoopHandling ReferenceLoopHandling.Ignore或者使用[JsonIgnore]标签手动断开循环。IL2CPP下的AOT问题如果直接使用官方NuGet包在iOS等使用IL2CPP编译的平台可能会因为泛型序列化/反序列化而崩溃。务必使用前面提到的为Unity特制的UPM包它包含了必要的AOT链接文件link.xml。版本冲突如果你的项目还引用了其他也依赖Newtonsoft.Json的插件如某些网络库可能会发生版本冲突。尽量统一版本或使用Assembly重定向。5. 工具三后起之秀 System.Text.Json 在Unity中的探索System.Text.Json是微软在.NET Core 3.0中推出的全新JSON库设计目标就是高性能和低内存分配。随着Unity对.NET Standard 2.1和.NET Core的支持它也逐渐可以在Unity项目中使用了。5.1 可用性检查与基础入门首先确认你的Unity版本。完整支持需要Unity 2021.2或更高版本且项目使用的是.NET Standard 2.1或.NET (Core)相关的API兼容层级。你可以在Player Settings - Configuration - Api Compatibility Level中查看。它的基础API设计上与Newtonsoft.Json类似但命名空间不同using System.Text.Json; using System.Text.Json.Serialization; // 用于特性标签 public class SimpleData { public string Name { get; set; } public int Value { get; set; } } // 序列化 SimpleData data new SimpleData { Name STJ, Value 42 }; string json JsonSerializer.Serialize(data, new JsonSerializerOptions { WriteIndented true }); // 反序列化 SimpleData newData JsonSerializer.DeserializeSimpleData(json);5.2 特性对比与迁移实践与Newtonsoft.Json相比System.Text.Json有一些设计上的不同默认更严格属性名称默认区分大小写且默认不忽略null值。这可能导致从Newtonsoft迁移时原本能解析的JSON现在报错。功能略少但专注性能初期版本功能不如Newtonsoft丰富如无TypeNameHandling但核心的序列化/反序列化路径经过高度优化。异步API原生支持提供了SerializeAsync和DeserializeAsync方法便于处理文件流或网络流。迁移实践与特性使用实现不区分大小写的属性匹配var options new JsonSerializerOptions { PropertyNameCaseInsensitive true // 反序列化时忽略属性名大小写 };自定义属性名和忽略public class Product { [JsonPropertyName(product_name)] // 对应JSON中的键 public string Name { get; set; } [JsonIgnore] // 忽略该属性 public decimal InternalDiscount { get; set; } }处理字典键非字符串System.Text.Json要求字典的键必须是字符串。如果你的字典键是enum或其他类型需要自定义转换器JsonConverter。处理多态不像Newtonsoft有TypeNameHandlingSystem.Text.Json需要通过自定义转换器或使用JsonDerivedType特性在.NET 7/8中引入Unity支持情况需测试来实现相对复杂。5.3 在Unity中的性能实测与适用场景在我的一个Unity 2022.3 LTS项目.NET Standard 2.1兼容性中的简单测试序列化/反序列化一个包含10个属性的对象10000次JsonUtility速度最快内存分配最少。System.Text.Json速度约为JsonUtility的1.5倍但比Newtonsoft.Json快2-3倍内存分配也远低于Newtonsoft。Newtonsoft.Json最慢内存分配最高但功能无短板。适用场景建议新项目且确定数据结构相对规范、不极度复杂可以考虑使用System.Text.Json作为主力享受其性能和现代API的优势。特别是对于纯服务端通信、处理大量配置数据的场景。性能敏感但JsonUtility功能不足如果数据结构稍微复杂比如需要字典但又对性能有较高要求可以评估System.Text.Json是否能满足需求它比引入Newtonsoft的负担小。需要处理Unity特有类型这点上System.Text.Json和Newtonsoft.Json一样需要为Vector3、Color等类型编写自定义转换器不如JsonUtility方便。重要提示在Unity中大规模使用System.Text.Json前务必在目标平台尤其是iOS/Android上进行充分的测试。由于其相对较新在IL2CPP下可能会遇到一些边界情况的问题需要关注Unity官方论坛和版本更新日志。6. 实战场景三大工具在典型Unity工作流中的应用理论说再多不如看实战。我们模拟几个Unity开发中最常见的场景看看如何选用和搭配这些工具。6.1 场景一游戏配置数据Config的加载与解析需求从Resources或StreamingAssets文件夹加载一个JSON格式的游戏平衡性配置表例如武器属性表。分析与选型配置数据通常在游戏启动时加载一次频率低。数据结构可能比较复杂包含列表、嵌套对象甚至需要字典来通过ID快速查找。对加载时的峰值性能有一定要求但并非帧频敏感。方案推荐使用Newtonsoft.Json功能强大能轻松应对复杂结构。一次加载缓存结果性能开销可接受。便于使用[JsonProperty]标签让JSON字段名和C#属性名解耦提高配置文件的可读性。实操代码片段// Weapons.json 内容示例 // [{id:sword_01,name:Iron Sword,damage:15,prefabPath:Weapons/Sword}...] [System.Serializable] public class WeaponConfig { [JsonProperty(id)] public string Id { get; set; } [JsonProperty(name)] public string DisplayName { get; set; } public int Damage { get; set; } public string PrefabPath { get; set; } } public class ConfigManager : MonoBehaviour { private Dictionarystring, WeaponConfig _weaponDict; void Start() { TextAsset configFile Resources.LoadTextAsset(Weapons); ListWeaponConfig configs JsonConvert.DeserializeObjectListWeaponConfig(configFile.text); _weaponDict configs.ToDictionary(c c.Id); // 转为字典便于查询 } public WeaponConfig GetWeaponConfig(string id) _weaponDict.TryGetValue(id, out var config) ? config : null; }6.2 场景二网络请求与API数据交互需求从游戏服务器请求玩家排行榜数据并解析成对象。分析与选型网络请求异步进行解析JSON是回调的一部分。数据结构由服务端定义可能经常变动需要较好的容错性如忽略未知字段。可能涉及嵌套、数组等结构。方案Newtonsoft.Json或System.Text.JsonNewtonsoft.Json依然是安全稳妥的选择MissingMemberHandling.Ignore可以轻松处理服务端新增字段。丰富的错误处理机制也很完善。System.Text.Json如果服务端API响应数据量很大且你的项目环境支持用它可以获得更好的解析性能。设置JsonSerializerOptions.PropertyNameCaseInsensitive true和AllowTrailingCommas等可以增加容错。实操要点以Newtonsoft为例using UnityEngine.Networking; using System.Collections; IEnumerator FetchLeaderboard() { using (UnityWebRequest request UnityWebRequest.Get(https://api.yourserver.com/leaderboard)) { yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { var settings new JsonSerializerSettings { MissingMemberHandling MissingMemberHandling.Ignore, // 忽略JSON中多出的字段 NullValueHandling NullValueHandling.Ignore }; LeaderboardData data JsonConvert.DeserializeObjectLeaderboardData(request.downloadHandler.text, settings); // 更新UI... } } }6.3 场景三高性能循环内的简单数据转换需求在游戏每帧的更新循环中处理大量从实体组件ECS或对象池中产生的简单状态数据并将其转换为JSON格式用于调试输出或日志。分析与选型性能极度敏感每帧可能执行成千上万次。数据结构极其简单通常只是几个基本类型的字段。功能需求简单不需要复杂特性。方案坚定不移地使用JsonUtility原生集成零额外开销。序列化简单结构的速度是数量级的优势。在这个场景下它的局限性不支持字典、私有字段等完全不是问题。实操示例[System.Serializable] public struct TransformSnapshot // 使用结构体更佳 { public Vector3 position; public Quaternion rotation; public float timestamp; } public class DebugSystem : MonoBehaviour { private ListTransformSnapshot _snapshots new ListTransformSnapshot(); void Update() { // 假设每帧收集大量实体的快照 foreach (var entity in _entities) { var snapshot new TransformSnapshot { position entity.Position, rotation entity.Rotation, timestamp Time.time }; _snapshots.Add(snapshot); // 如果需要立即转换为JSON字符串用于网络发送或日志示例 // string json JsonUtility.ToJson(snapshot); // 速度极快 } // 批量处理... } }7. 疑难杂症与性能调优终极指南即使选对了工具用不对也会出问题。这里汇总一些高频问题和优化技巧。7.1 常见错误与异常处理JsonUtility序列化返回空字符串{}原因类没有加[System.Serializable]标签或者只有属性没有公共字段。排查检查类定义确保是public字段且带有序列化标签。Newtonsoft.Json抛出JsonSerializationException: Self referencing loop detected原因对象存在循环引用如父子对象互相引用。解决var settings new JsonSerializerSettings { ReferenceLoopHandling ReferenceLoopHandling.Ignore // 忽略循环引用 }; // 或者在特定属性上使用 [JsonIgnore]反序列化后字段为默认值0或null原因JsonUtilityJSON中的字段名与类中的公共字段名大小写不匹配。JsonUtility默认是大小写敏感的。原因Newtonsoft可能使用了ContractResolver如驼峰转换但JSON格式不匹配或者属性有setter但非public。排查仔细对比JSON字符串和类定义。对于Newtonsoft可以设置MissingMemberHandling MissingMemberHandling.Error来帮助定位。System.Text.Json无法反序列化接口或抽象类属性原因它默认不支持多态反序列化。解决需要编写自定义的JsonConverterT并在选项或属性上指定。这是从Newtonsoft迁移时的一个主要难点。7.2 高级性能优化策略缓存序列化器/设置针对Newtonsoft和System.Text.Json反复创建JsonSerializerSettings或JsonSerializerOptions会产生GC垃圾回收压力。应该将它们定义为静态只读成员。// Newtonsoft private static readonly JsonSerializerSettings MySettings new JsonSerializerSettings { ... }; // System.Text.Json private static readonly JsonSerializerOptions MyOptions new JsonSerializerOptions { ... };使用流式API处理超大文件对于几十MB甚至更大的JSON配置文件如开放世界的地图数据不要用JsonConvert.DeserializeObjectT(string)一次性读入内存。使用JsonTextReader进行流式读取按需处理。为JsonUtility设计扁平化数据结构既然JsonUtility快就尽量让它有用武之地。对于复杂数据可以设计一个“传输层”的扁平化DTOData Transfer Object用JsonUtility序列化这个简单的DTO然后在业务层再转换成复杂的领域模型。虽然多了一步转换但可能比直接用Newtonsoft序列化复杂对象更快。避免在频繁调用的代码路径中进行字符串操作JsonUtility.ToJson()和FromJson()会产生字符串GC。在性能关键的循环中如果JSON结构固定可以考虑使用Unity.Collections下的NativeArraybyte配合Unity.Serialization.Json一个较新的、无GC的JSON序列化实验包适用于ECS等更底层的方式但这属于高级优化范畴。7.3 版本兼容性与未来展望Unity版本迭代关注Unity每年发布的LTS长期支持版本它们会更新底层的.NET运行时版本。.NET Standard 2.1和.NET (Core)的支持意味着更多现代C#特性和库如System.Text.Json的完整功能将变得可用。System.Text.Json的进化微软在持续优化和增强这个库。关注其新版本特性如源生成器Source Generators可以在编译时生成高效的序列化代码彻底避免反射开销一旦Unity的编译器工具链支持这将是游戏开发中JSON处理的性能利器。混合使用策略一个成熟的Unity项目不必拘泥于一种工具。完全可以三管齐下高频简单数据用JsonUtility主要业务配置用Newtonsoft.Json在新模块或性能瓶颈处尝试System.Text.Json。关键在于为每个任务选择最合适的“武器”。说到底工具是死的人是活的。没有最好的工具只有最合适的场景。我的经验是在项目初期就根据数据结构的复杂度和性能预期做一个简单的评估和约定能省去后期大量的重构和调试时间。对于大部分中小型Unity项目Newtonsoft.Json依然是功能性和社区支持上的“压舱石”。但对于新项目尤其是对包体大小和运行性能有苛刻要求的项目花点时间评估和测试System.Text.Json与JsonUtility的组合方案可能会带来意想不到的收益。记住在JSON解析这条路上清晰的数据结构设计往往比选择哪个解析库更重要。
Unity JSON解析工具全解析：JsonUtility、Newtonsoft.Json与System.Text.Json实战对比
发布时间：2026/8/1 5:45:10
1. 项目概述为什么Unity开发者绕不开JSON解析如果你在Unity里做过数据管理、配置读取或者网络通信那你肯定跟JSON打过交道。这玩意儿现在几乎是数据交换的“世界语”从游戏存档、关卡配置到从服务器拉取排行榜、道具列表再到和第三方API对接JSON的身影无处不在。但Unity本身对JSON的支持怎么说呢有点“基础”。自带的JsonUtility用起来是快但限制也多稍微复杂点的数据结构或者需要点灵活性的场景它就有点力不从心了。所以我们这些Unity老鸟的日常工具箱里总会备着几款第三方的JSON解析工具。它们各有各的脾气和擅长领域选对了工具开发效率能提升一大截选错了或者用错了可能就是无尽的调试和性能瓶颈。今天我就结合自己这些年踩过的坑和积累的经验给你掰扯掰扯Unity里最常用、也最值得推荐的三大JSON工具Unity原生的JsonUtility、功能强大的Newtonsoft.Json也就是Json.NET以及后起之秀System.Text.Json。我会告诉你它们各自适合什么场景怎么用以及那些官方文档里不会写的“坑”和技巧。2. 三大工具核心特性与选型指南面对一个JSON解析需求别急着写代码先花两分钟想想该用哪个工具。选型不对努力白费。下面这张表能帮你快速抓住核心区别特性维度Unity JsonUtilityNewtonsoft.Json (Json.NET)System.Text.Json来源与集成Unity引擎原生无需额外导入第三方库需通过Package Manager或手动导入.NET Core 3.0 原生Unity 2021.2 部分支持序列化/反序列化速度极快针对简单结构优化中等偏慢功能丰富导致开销快设计目标就是高性能功能丰富度极简仅支持基础功能极其丰富高度可定制较丰富平衡性能与功能对Unity类型支持原生完美支持如Vector3, Color需自定义转换器Converter需自定义转换器Converter复杂数据支持弱不支持字典、多态、私有字段等强全支持高度灵活中等部分支持需配置推荐使用场景1. 简单的数据类MonoBehaviour序列化2. 性能敏感的简单数据流3. 快速原型验证1. 复杂数据结构含字典、接口、继承2. 需要高度定制化序列化规则3. 与旧有.NET生态库交互1. Unity 2021.2 新项目2. 对性能有要求且结构不太复杂3. 希望使用.NET官方未来主流方案选型心法求快、求简单用JsonUtility如果你的数据类就是一堆public字段没继承、没接口、没字典纯粹为了存个配置或者临时传个数据JsonUtility是不二之选。它的速度优势在移动端高频调用时非常明显。求稳、求功能全用Newtonsoft.Json如果你的项目已经用了它或者数据结构非常复杂比如游戏存档包含各种类型的物品、技能树需要处理多态、忽略某些字段、自定义日期格式等Json.NET依然是“瑞士军刀”社区资源和解决方案也最全。求新、求平衡尝试System.Text.Json如果是全新的Unity 2021.2项目特别是面向较新.NET版本可以考虑用它。它在性能和功能上取得了不错的平衡而且是.NET官方主推的方向未来兼容性和性能优化更有保障。注意System.Text.Json在Unity中的支持是逐步完善的。在较早的Unity版本或特定的.NET Standard版本下某些API可能不可用。使用前最好在目标Unity版本中测试一下核心功能。3. 工具一Unity原生JsonUtility 深度解析与实战JsonUtility是Unity亲儿子集成在UnityEngine命名空间下开箱即用。它的设计哲学是简单和性能为此牺牲了灵活性。3.1 核心API与基础用法它的API简单到令人发指主要就两个静态方法string ToJson(object obj, bool prettyPrint false): 将对象序列化成JSON字符串。T FromJsonT(string json): 将JSON字符串反序列化成指定类型的对象。还有一个FromJsonOverwrite用于将JSON数据反序列化并覆盖到一个已存在对象的公共字段上适合部分更新。基础示例假设我们有一个玩家数据类[System.Serializable] // 这是关键JsonUtility只处理标记为可序列化的类 public class PlayerData { public string playerName; public int level; public float health; // public Vector3 position; // Unity基础类型直接支持 }序列化和反序列化PlayerData player new PlayerData { playerName Hero, level 10, health 85.5f }; // 序列化 string json JsonUtility.ToJson(player, true); // prettyPrint为true输出格式化后的JSON Debug.Log(json); // 输出 // { // playerName: Hero, // level: 10, // health: 85.5 // } // 反序列化 string receivedJson {\playerName\:\Villain\,\level\:99,\health\:100.0}; PlayerData newPlayer JsonUtility.FromJsonPlayerData(receivedJson); Debug.Log(newPlayer.playerName); // 输出: Villain3.2 优势、局限与实战避坑指南优势零依赖性能极致由于是引擎原生且功能单纯在序列化简单POCOPlain Old C# Object时速度远超其他第三方库对移动设备友好。完美支持Unity特有类型Vector2/3/4,Quaternion,Color,Rect,Bounds等类型可以直接序列化/反序列化非常方便。与Unity工作流集成好[System.Serializable]标签同时也是Unity Inspector面板显示的条件一套标签两处使用。局限与“坑”必须使用[Serializable]标签这是最大的限制。类、结构体必须标记此标签且只处理公有字段public fields。属性Properties、私有/受保护字段默认都会被忽略。不支持复杂类型不支持字典Dictionary这是最常遇到的坑。如果你尝试序列化一个Dictionarystring, int它会直接忽略。不支持多态继承反序列化时无法根据JSON内容自动识别并创建派生类对象。不支持接口Interface类型字段。不支持ListListT这类嵌套泛型集合但ListT和数组T[]是支持的。反序列化时构造函数不会被调用对象是通过System.Activator创建的不会走你定义的构造函数。实战避坑技巧应对字典需求如果需要字典结构可以将其包装在一个可序列化的类中用两个List分别存储键和值或者直接使用ListKeyValuePair。虽然麻烦但在性能关键路径上这比引入Newtonsoft.Json更高效。[System.Serializable] public class SerializableDictionaryTKey, TValue { public ListTKey keys new ListTKey(); public ListTValue values new ListTValue(); // 可以添加方法将其转换成真正的Dictionary }处理私有数据如果确实需要序列化私有字段可以将其公开或者使用公共属性配合[SerializeField]标签这样Inspector和JsonUtility都能识别。部分更新对象使用JsonUtility.FromJsonOverwrite可以只更新JSON中提供的字段保留对象原有的其他字段值。这在处理网络增量更新时很有用。4. 工具二功能王者 Newtonsoft.Json (Json.NET) 全方位攻略如果JsonUtility是“水果刀”那Newtonsoft.Json就是“万能工具箱”。它几乎能处理你能想到的任何JSON相关场景但也因此更重。4.1 在Unity中的安装与配置现在最推荐的方式是通过Unity的Package Manager安装打开Window - Package Manager。点击左上角“”号选择“Add package from git URL...”。输入https://github.com/jilleJr/Newtonsoft.Json-for-Unity.git#upm这是一个专门为Unity打包的版本解决了原生Newtonsoft.Json在IL2CPP下可能存在的AOT编译问题。等待安装完成。安装后命名空间为Newtonsoft.Json。4.2 核心功能实战与高级特性基础使用和JsonUtility类似但功能强大得多using Newtonsoft.Json; public class ComplexData { public string Name { get; set; } // 支持属性 private int secretCode; // 默认不支持私有字段但可通过设置支持 public Dictionarystring, object Stats { get; set; } // 支持字典 public IItem EquippedItem { get; set; } // 支持接口但需要配置 } // 序列化 ComplexData data new ComplexData { Name Test, Stats new Dictionarystring, object { { Atk, 100 } } }; string json JsonConvert.SerializeObject(data, Formatting.Indented); // 反序列化 ComplexData newData JsonConvert.DeserializeObjectComplexData(json);高级特性详解自定义序列化设置JsonSerializerSettings这是它的灵魂。JsonSerializerSettings settings new JsonSerializerSettings { NullValueHandling NullValueHandling.Ignore, // 忽略null值 DefaultValueHandling DefaultValueHandling.Ignore, // 忽略类型默认值 ContractResolver new CamelCasePropertyNamesContractResolver(), // 属性名转为驼峰命名 Converters new ListJsonConverter { new StringEnumConverter() }, // 枚举转字符串 TypeNameHandling TypeNameHandling.Auto // 处理多态JSON中会包含类型信息 }; string jsonWithSettings JsonConvert.SerializeObject(data, settings);处理多态继承通过TypeNameHandling设置JSON中会自动添加$type字段记录具体类型反序列化时能正确还原。settings.TypeNameHandling TypeNameHandling.All; // 序列化一个基类引用实际指向派生类对象 BaseClass obj new DerivedClass(); string polyJson JsonConvert.SerializeObject(obj, settings); // 反序列化时能正确得到DerivedClass实例 BaseClass restored JsonConvert.DeserializeObjectBaseClass(polyJson, settings);使用属性标签进行精细控制public class Player { [JsonProperty(player_name)] // 序列化后字段名为player_name public string PlayerName { get; set; } [JsonIgnore] // 完全忽略此属性 public string TemporaryToken { get; set; } [JsonProperty(Required Required.Always)] // 该属性在JSON中必须存在 public int Id { get; set; } }4.3 性能优化与常见问题排查性能优化点重用JsonSerializerSettings不要每次序列化都new一个创建开销不小。应该将其定义为静态只读成员。使用流式API处理大JSON对于非常大的JSON文件使用JsonTextReader和JsonTextWriter进行流式读写避免一次性加载到内存。using (StreamReader file File.OpenText(large.json)) using (JsonTextReader reader new JsonTextReader(file)) { while (reader.Read()) { // 逐Token处理 } }避免过度使用TypeNameHandling它会增加JSON大小并带来轻微性能开销且可能存在安全风险反序列化时可能实例化任意类型仅在必需时使用。常见问题排查循环引用错误对象A引用BB又引用A序列化时会抛出JsonSerializationException。解决方案在设置中ReferenceLoopHandling ReferenceLoopHandling.Ignore或者使用[JsonIgnore]标签手动断开循环。IL2CPP下的AOT问题如果直接使用官方NuGet包在iOS等使用IL2CPP编译的平台可能会因为泛型序列化/反序列化而崩溃。务必使用前面提到的为Unity特制的UPM包它包含了必要的AOT链接文件link.xml。版本冲突如果你的项目还引用了其他也依赖Newtonsoft.Json的插件如某些网络库可能会发生版本冲突。尽量统一版本或使用Assembly重定向。5. 工具三后起之秀 System.Text.Json 在Unity中的探索System.Text.Json是微软在.NET Core 3.0中推出的全新JSON库设计目标就是高性能和低内存分配。随着Unity对.NET Standard 2.1和.NET Core的支持它也逐渐可以在Unity项目中使用了。5.1 可用性检查与基础入门首先确认你的Unity版本。完整支持需要Unity 2021.2或更高版本且项目使用的是.NET Standard 2.1或.NET (Core)相关的API兼容层级。你可以在Player Settings - Configuration - Api Compatibility Level中查看。它的基础API设计上与Newtonsoft.Json类似但命名空间不同using System.Text.Json; using System.Text.Json.Serialization; // 用于特性标签 public class SimpleData { public string Name { get; set; } public int Value { get; set; } } // 序列化 SimpleData data new SimpleData { Name STJ, Value 42 }; string json JsonSerializer.Serialize(data, new JsonSerializerOptions { WriteIndented true }); // 反序列化 SimpleData newData JsonSerializer.DeserializeSimpleData(json);5.2 特性对比与迁移实践与Newtonsoft.Json相比System.Text.Json有一些设计上的不同默认更严格属性名称默认区分大小写且默认不忽略null值。这可能导致从Newtonsoft迁移时原本能解析的JSON现在报错。功能略少但专注性能初期版本功能不如Newtonsoft丰富如无TypeNameHandling但核心的序列化/反序列化路径经过高度优化。异步API原生支持提供了SerializeAsync和DeserializeAsync方法便于处理文件流或网络流。迁移实践与特性使用实现不区分大小写的属性匹配var options new JsonSerializerOptions { PropertyNameCaseInsensitive true // 反序列化时忽略属性名大小写 };自定义属性名和忽略public class Product { [JsonPropertyName(product_name)] // 对应JSON中的键 public string Name { get; set; } [JsonIgnore] // 忽略该属性 public decimal InternalDiscount { get; set; } }处理字典键非字符串System.Text.Json要求字典的键必须是字符串。如果你的字典键是enum或其他类型需要自定义转换器JsonConverter。处理多态不像Newtonsoft有TypeNameHandlingSystem.Text.Json需要通过自定义转换器或使用JsonDerivedType特性在.NET 7/8中引入Unity支持情况需测试来实现相对复杂。5.3 在Unity中的性能实测与适用场景在我的一个Unity 2022.3 LTS项目.NET Standard 2.1兼容性中的简单测试序列化/反序列化一个包含10个属性的对象10000次JsonUtility速度最快内存分配最少。System.Text.Json速度约为JsonUtility的1.5倍但比Newtonsoft.Json快2-3倍内存分配也远低于Newtonsoft。Newtonsoft.Json最慢内存分配最高但功能无短板。适用场景建议新项目且确定数据结构相对规范、不极度复杂可以考虑使用System.Text.Json作为主力享受其性能和现代API的优势。特别是对于纯服务端通信、处理大量配置数据的场景。性能敏感但JsonUtility功能不足如果数据结构稍微复杂比如需要字典但又对性能有较高要求可以评估System.Text.Json是否能满足需求它比引入Newtonsoft的负担小。需要处理Unity特有类型这点上System.Text.Json和Newtonsoft.Json一样需要为Vector3、Color等类型编写自定义转换器不如JsonUtility方便。重要提示在Unity中大规模使用System.Text.Json前务必在目标平台尤其是iOS/Android上进行充分的测试。由于其相对较新在IL2CPP下可能会遇到一些边界情况的问题需要关注Unity官方论坛和版本更新日志。6. 实战场景三大工具在典型Unity工作流中的应用理论说再多不如看实战。我们模拟几个Unity开发中最常见的场景看看如何选用和搭配这些工具。6.1 场景一游戏配置数据Config的加载与解析需求从Resources或StreamingAssets文件夹加载一个JSON格式的游戏平衡性配置表例如武器属性表。分析与选型配置数据通常在游戏启动时加载一次频率低。数据结构可能比较复杂包含列表、嵌套对象甚至需要字典来通过ID快速查找。对加载时的峰值性能有一定要求但并非帧频敏感。方案推荐使用Newtonsoft.Json功能强大能轻松应对复杂结构。一次加载缓存结果性能开销可接受。便于使用[JsonProperty]标签让JSON字段名和C#属性名解耦提高配置文件的可读性。实操代码片段// Weapons.json 内容示例 // [{id:sword_01,name:Iron Sword,damage:15,prefabPath:Weapons/Sword}...] [System.Serializable] public class WeaponConfig { [JsonProperty(id)] public string Id { get; set; } [JsonProperty(name)] public string DisplayName { get; set; } public int Damage { get; set; } public string PrefabPath { get; set; } } public class ConfigManager : MonoBehaviour { private Dictionarystring, WeaponConfig _weaponDict; void Start() { TextAsset configFile Resources.LoadTextAsset(Weapons); ListWeaponConfig configs JsonConvert.DeserializeObjectListWeaponConfig(configFile.text); _weaponDict configs.ToDictionary(c c.Id); // 转为字典便于查询 } public WeaponConfig GetWeaponConfig(string id) _weaponDict.TryGetValue(id, out var config) ? config : null; }6.2 场景二网络请求与API数据交互需求从游戏服务器请求玩家排行榜数据并解析成对象。分析与选型网络请求异步进行解析JSON是回调的一部分。数据结构由服务端定义可能经常变动需要较好的容错性如忽略未知字段。可能涉及嵌套、数组等结构。方案Newtonsoft.Json或System.Text.JsonNewtonsoft.Json依然是安全稳妥的选择MissingMemberHandling.Ignore可以轻松处理服务端新增字段。丰富的错误处理机制也很完善。System.Text.Json如果服务端API响应数据量很大且你的项目环境支持用它可以获得更好的解析性能。设置JsonSerializerOptions.PropertyNameCaseInsensitive true和AllowTrailingCommas等可以增加容错。实操要点以Newtonsoft为例using UnityEngine.Networking; using System.Collections; IEnumerator FetchLeaderboard() { using (UnityWebRequest request UnityWebRequest.Get(https://api.yourserver.com/leaderboard)) { yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { var settings new JsonSerializerSettings { MissingMemberHandling MissingMemberHandling.Ignore, // 忽略JSON中多出的字段 NullValueHandling NullValueHandling.Ignore }; LeaderboardData data JsonConvert.DeserializeObjectLeaderboardData(request.downloadHandler.text, settings); // 更新UI... } } }6.3 场景三高性能循环内的简单数据转换需求在游戏每帧的更新循环中处理大量从实体组件ECS或对象池中产生的简单状态数据并将其转换为JSON格式用于调试输出或日志。分析与选型性能极度敏感每帧可能执行成千上万次。数据结构极其简单通常只是几个基本类型的字段。功能需求简单不需要复杂特性。方案坚定不移地使用JsonUtility原生集成零额外开销。序列化简单结构的速度是数量级的优势。在这个场景下它的局限性不支持字典、私有字段等完全不是问题。实操示例[System.Serializable] public struct TransformSnapshot // 使用结构体更佳 { public Vector3 position; public Quaternion rotation; public float timestamp; } public class DebugSystem : MonoBehaviour { private ListTransformSnapshot _snapshots new ListTransformSnapshot(); void Update() { // 假设每帧收集大量实体的快照 foreach (var entity in _entities) { var snapshot new TransformSnapshot { position entity.Position, rotation entity.Rotation, timestamp Time.time }; _snapshots.Add(snapshot); // 如果需要立即转换为JSON字符串用于网络发送或日志示例 // string json JsonUtility.ToJson(snapshot); // 速度极快 } // 批量处理... } }7. 疑难杂症与性能调优终极指南即使选对了工具用不对也会出问题。这里汇总一些高频问题和优化技巧。7.1 常见错误与异常处理JsonUtility序列化返回空字符串{}原因类没有加[System.Serializable]标签或者只有属性没有公共字段。排查检查类定义确保是public字段且带有序列化标签。Newtonsoft.Json抛出JsonSerializationException: Self referencing loop detected原因对象存在循环引用如父子对象互相引用。解决var settings new JsonSerializerSettings { ReferenceLoopHandling ReferenceLoopHandling.Ignore // 忽略循环引用 }; // 或者在特定属性上使用 [JsonIgnore]反序列化后字段为默认值0或null原因JsonUtilityJSON中的字段名与类中的公共字段名大小写不匹配。JsonUtility默认是大小写敏感的。原因Newtonsoft可能使用了ContractResolver如驼峰转换但JSON格式不匹配或者属性有setter但非public。排查仔细对比JSON字符串和类定义。对于Newtonsoft可以设置MissingMemberHandling MissingMemberHandling.Error来帮助定位。System.Text.Json无法反序列化接口或抽象类属性原因它默认不支持多态反序列化。解决需要编写自定义的JsonConverterT并在选项或属性上指定。这是从Newtonsoft迁移时的一个主要难点。7.2 高级性能优化策略缓存序列化器/设置针对Newtonsoft和System.Text.Json反复创建JsonSerializerSettings或JsonSerializerOptions会产生GC垃圾回收压力。应该将它们定义为静态只读成员。// Newtonsoft private static readonly JsonSerializerSettings MySettings new JsonSerializerSettings { ... }; // System.Text.Json private static readonly JsonSerializerOptions MyOptions new JsonSerializerOptions { ... };使用流式API处理超大文件对于几十MB甚至更大的JSON配置文件如开放世界的地图数据不要用JsonConvert.DeserializeObjectT(string)一次性读入内存。使用JsonTextReader进行流式读取按需处理。为JsonUtility设计扁平化数据结构既然JsonUtility快就尽量让它有用武之地。对于复杂数据可以设计一个“传输层”的扁平化DTOData Transfer Object用JsonUtility序列化这个简单的DTO然后在业务层再转换成复杂的领域模型。虽然多了一步转换但可能比直接用Newtonsoft序列化复杂对象更快。避免在频繁调用的代码路径中进行字符串操作JsonUtility.ToJson()和FromJson()会产生字符串GC。在性能关键的循环中如果JSON结构固定可以考虑使用Unity.Collections下的NativeArraybyte配合Unity.Serialization.Json一个较新的、无GC的JSON序列化实验包适用于ECS等更底层的方式但这属于高级优化范畴。7.3 版本兼容性与未来展望Unity版本迭代关注Unity每年发布的LTS长期支持版本它们会更新底层的.NET运行时版本。.NET Standard 2.1和.NET (Core)的支持意味着更多现代C#特性和库如System.Text.Json的完整功能将变得可用。System.Text.Json的进化微软在持续优化和增强这个库。关注其新版本特性如源生成器Source Generators可以在编译时生成高效的序列化代码彻底避免反射开销一旦Unity的编译器工具链支持这将是游戏开发中JSON处理的性能利器。混合使用策略一个成熟的Unity项目不必拘泥于一种工具。完全可以三管齐下高频简单数据用JsonUtility主要业务配置用Newtonsoft.Json在新模块或性能瓶颈处尝试System.Text.Json。关键在于为每个任务选择最合适的“武器”。说到底工具是死的人是活的。没有最好的工具只有最合适的场景。我的经验是在项目初期就根据数据结构的复杂度和性能预期做一个简单的评估和约定能省去后期大量的重构和调试时间。对于大部分中小型Unity项目Newtonsoft.Json依然是功能性和社区支持上的“压舱石”。但对于新项目尤其是对包体大小和运行性能有苛刻要求的项目花点时间评估和测试System.Text.Json与JsonUtility的组合方案可能会带来意想不到的收益。记住在JSON解析这条路上清晰的数据结构设计往往比选择哪个解析库更重要。
