1. 项目概述为什么Unity开发者需要关注JSON处理如果你在Unity项目里用过JsonUtility然后转头去尝试序列化一个稍微复杂点的类比如里面带个Dictionary或者List自定义类大概率会碰一鼻子灰然后开始满世界找替代方案。这时候Newtonsoft.Json现在也叫Json.NET这个名字就会像救星一样出现在你眼前。它在.NET生态里几乎是JSON处理的代名词功能强大到令人发指。但当你兴冲冲地想把它搬进Unity时又会发现一堆坑版本兼容性、IL2CPP支持、AOT编译限制、性能问题还有那个官方包上明晃晃的“内部使用风险自负”的警告。这就是我写这篇指南的初衷。这不是一篇简单的“怎么安装包”的教程而是一个完整的、从踩坑到填坑的实战总结。我会带你彻底搞懂在Unity里使用Newtonsoft.Json的完整适配方案涵盖从包管理、基础序列化、到高级特性、性能优化再到那些官方文档里不会写的“坑”和解决方案。无论你是想处理游戏配置、存档数据还是和服务器进行复杂的通信这套方案都能让你手里的JSON工具变得既强大又可靠。2. 核心思路与方案选型Unity下的Newtonsoft.Json生存之道在Unity里用第三方库尤其是Newtonsoft.Json这种重量级的不能像在普通.NET项目里那样直接Install-Package就完事了。你得把它当成一个“外来物种”思考如何让它在这个特定的生态环境Unity的脚本后端、编译管线、运行时环境里健康存活并高效工作。2.1 为什么是Newtonsoft.Json而不是JsonUtility或System.Text.JsonUnity自带的JsonUtility是轻量级选手它基于Unity的序列化系统优点是快、内存开销小但缺点极其明显不支持多态、不支持字典、不支持私有字段、对复杂嵌套结构和接口束手无策。它只认[Serializable]标签和简单的字段结构稍微复杂点的业务模型就得拆解得面目全非。System.Text.Json是.NET Core 3.0后官推的现代库性能理论上更优。但在Unity里尤其是面向IL2CPP和较老.NET Standard版本时它的支持并不完整可能会遇到反射或源代码生成Source Generator相关的问题且生态系统和社区熟悉度暂时不如Newtonsoft.Json。Newtonsoft.Json则是一个“全能战士”。它通过强大的反射和契约Contract系统几乎能处理你能想到的任何序列化场景自定义转换器、忽略循环引用、处理默认值、多态类型识别……它的API经过十多年打磨异常成熟和稳定。对于Unity项目尤其是中大型项目、需要与复杂后端API交互、或数据模型频繁变动的项目Newtonsoft.Json提供的灵活性和可靠性是无可替代的。2.2 Unity官方包 vs 手动导入风险与收益的权衡搜索资料里提到了com.unity.nuget.newtonsoft-json这个官方包。它的存在本身就是一个重要信号Unity内部也在用它。这个包的本质是把特定版本如12.0.301的Newtonsoft.Json.dll打包成了Unity Package Manager (UPM) 可识别的格式。使用官方包的优势便捷通过UPM或直接修改Packages/manifest.json即可一键添加。版本管理版本号清晰易于升级或回滚。潜在优化Unity可能对其进行了某些适配尽管文档未说明。但你必须清醒认识其风险正如资料中两次强调的“This is a package intended for internal Unity Development Projects and as such this package is not supported. Use at your own risk.” 这句话翻译过来就是这是我们Unity自己内部用的出了问题别来找我们你自己看着办。这意味着无官方技术支持如果你遇到BugUnity官方没有义务帮你解决。版本更新不确定这个包是否会跟随上游Newtonsoft.Json更新更新周期多长都是未知数。潜在兼容性问题这个特定版本12.0.301可能与你的其他插件尤其是那些也捆绑了Newtonsoft.Json的插件发生DLL冲突。手动导入方案 另一种方法是直接从NuGet下载Newtonsoft.Json的DLL或者使用其源码直接放入项目的Assets/Plugins文件夹。这样做你获得了版本控制的完全自主权可以选用更新或更稳定的版本例如13.0.1。但你需要自行处理可能存在的.NET版本兼容性问题并确保它与你项目中的其他.NET库和谐共处。我的实操心得与选择对于大多数商业项目我倾向于使用官方UPM包。原因很简单省心。UPM管理依赖干净利落避免了DLL地狱。虽然有不支持的警告但Newtonsoft.Json本身极其稳定12.0.301也是一个久经考验的版本。在数百个项目的实践中我极少遇到直接由这个包引起的致命问题。真正的“坑”往往在于如何使用它而不是包本身。如果你追求极致的新特性或对某个Bug有特定修复需求再考虑手动导入。2.3 目标环境考量Mono vs IL2CPP AOT的挑战这是Unity适配的核心战场。Mono脚本后端反射工作正常Newtonsoft.Json的所有功能基本可以无缝使用。IL2CPP脚本后端 AOT编译这是问题的重灾区。AOTAhead-of-Time编译要求所有可能被执行的代码必须在编译期就确定。而Newtonsoft.Json大量依赖运行时反射例如通过Type.GetProperty来获取属性信息和动态代码生成例如为特定类型生成高效的序列化器这些在AOT环境下会引发运行时异常最常见的错误是ExecutionEngineException或提示某个方法/属性找不到。因此我们的适配方案必须包含针对IL2CPP的预置措施。核心思路是“提前告诉编译器需要什么”主要手段是链接器配置link.xml防止必要的代码被裁剪掉。AOT预编译AOT Compilation更高级的方案强制编译器为泛型或反射使用的类型生成代码。3. 基础集成与关键配置实战理论说完我们开始动手。假设你决定采用官方UPM包这是最普遍的起点。3.1 安装与基础验证打开你的Unity项目有两种方式安装方式一推荐编辑Packages/manifest.json文件在dependencies块中添加{ dependencies: { com.unity.nuget.newtonsoft-json: 2.0.2, // ... 其他依赖 } }保存后Unity会自动解析并导入包。方式二在Unity Editor的Package Manager窗口中点击“”号选择“Add package from git URL...”输入com.unity.nuget.newtonsoft-json。安装完成后创建一个简单的测试脚本验证基础功能是否正常using Newtonsoft.Json; using UnityEngine; public class NewtonsoftTest : MonoBehaviour { [System.Serializable] // 这个标签对Newtonsoft.Json不是必须的但加上也无妨 public class PlayerData { public string Name; public int Level; public Vector3 Position; // 注意Unity原生结构体 } void Start() { var player new PlayerData { Name Hero, Level 99, Position new Vector3(1, 2, 3) }; // 序列化 string json JsonConvert.SerializeObject(player, Formatting.Indented); Debug.Log(Serialized JSON:\n json); // 反序列化 PlayerData deserializedPlayer JsonConvert.DeserializeObjectPlayerData(json); Debug.Log($Deserialized: Name{deserializedPlayer.Name}, Level{deserializedPlayer.Level}); } }运行后能在Console看到格式化的JSON输出和反序列化结果说明基础集成成功。但你可能立刻会发现一个问题Vector3被序列化成什么了答案是类似{x:1.0, y:2.0, z:3.0}的结构。这引出了我们的第一个高级话题处理Unity特殊类型。3.2 核心配置序列化设置JsonSerializerSettingsJsonSerializerSettings是你控制Newtonsoft.Json行为的核心枢纽。创建并配置一个全局或模块级的Settings对象是最佳实践。public static class JsonSettings { public static readonly JsonSerializerSettings Default new JsonSerializerSettings { // 格式化输出便于调试生产环境可关闭 Formatting Formatting.Indented, // 处理循环引用例如两个对象互相引用。Ignore会在序列化时跳过已序列化的对象引用。 ReferenceLoopHandling ReferenceLoopHandling.Ignore, // 处理空值。Ignore会在序列化时跳过值为null的字段。 NullValueHandling NullValueHandling.Ignore, // 处理默认值。Ignore会在序列化时跳过值等于类型默认值的字段如int的0。 DefaultValueHandling DefaultValueHandling.Ignore, // 非常重要定义如何转换日期格式。IsoDateFormat是跨平台兼容性最好的。 DateFormatHandling DateFormatHandling.IsoDateFormat, // 处理未匹配的成员。Error会在反序列化时如果JSON中有但C#对象没有对应字段则抛出异常。这有助于发现数据格式错误。 MissingMemberHandling MissingMemberHandling.Error, // 类型名称处理。用于多态序列化稍后详解。 TypeNameHandling TypeNameHandling.None, // 默认None安全考虑 // 合约解析器可以自定义序列化行为是高级功能的入口。 // ContractResolver new MyCustomContractResolver() }; } // 使用配置进行序列化/反序列化 string json JsonConvert.SerializeObject(obj, JsonSettings.Default); var obj JsonConvert.DeserializeObjectT(json, JsonSettings.Default);3.3 征服IL2CPP链接器配置与代码裁剪这是确保项目在发布尤其是移动端时不崩溃的关键一步。IL2CPP的代码裁剪器Linker为了减小包体会移除它认为“未被使用”的代码。而反射恰恰是“静态分析”难以识别的“使用”方式。解决方案创建Assets/link.xml文件这个文件的作用是告诉Unity链接器“这些类型或程序集很重要别动它们”。linker assembly fullnameNewtonsoft.Json preserveall/ !-- 保留整个Newtonsoft.Json程序集最省事但也最保守可能增加包体 -- !-- 更精细的控制示例只保留特定类型 -- !-- assembly fullnameNewtonsoft.Json type fullnameNewtonsoft.Json.JsonConvert preserveall/ type fullnameNewtonsoft.Json.Serialization.DefaultContractResolver preserveall/ /assembly -- !-- 保留你项目中所有可能通过反射使用的类型 -- assembly fullnameYourGame.Assembly !-- 如果你的数据模型在某个程序集中确保其所有类型不被裁剪 -- type fullnameYourGame.DataModel.* preserveall/ /assembly !-- 保留System.Collections.Generic下的关键泛型容器它们常被反射使用 -- assembly fullnamemscorlib type fullnameSystem.Collections.Generic.Dictionary2 preserveall/ type fullnameSystem.Collections.Generic.List1 preserveall/ type fullnameSystem.Collections.Generic.HashSet1 preserveall/ /assembly /linker踩坑记录link.xml的路径必须是Assets/link.xml或Assets/Plugins/link.xml放在子文件夹里可能不生效。另外preserveall会保留类型的所有成员包括私有方法这比preservenothing或默认行为更安全但体积更大。你需要根据项目在包体大小和稳定性之间权衡。对于核心数据模型我通常选择preserveall。4. 高级特性与Unity特化处理基础打通后我们来解决实际开发中更复杂的需求。4.1 处理Unity特有类型Vector3, Quaternion, Color等Newtonsoft.Json不认识Vector3。默认情况下它会序列化其公有字段x, y, z这虽然能用但格式可能不符合你的要求或者你想把它序列化成更简洁的数组形式[1,2,3]。方案编写自定义JsonConverterusing Newtonsoft.Json; using Newtonsoft.Json.Linq; using UnityEngine; public class Vector3Converter : JsonConverterVector3 { public override void WriteJson(JsonWriter writer, Vector3 value, JsonSerializer serializer) { // 将Vector3序列化为 [x, y, z] 数组格式 writer.WriteStartArray(); writer.WriteValue(value.x); writer.WriteValue(value.y); writer.WriteValue(value.z); writer.WriteEndArray(); } public override Vector3 ReadJson(JsonReader reader, Type objectType, Vector3 existingValue, bool hasExistingValue, JsonSerializer serializer) { // 从JSON Token中读取数组并解析 JArray array JArray.Load(reader); return new Vector3(array[0].Valuefloat(), array[1].Valuefloat(), array[2].Valuefloat()); } } // 为Color, Quaternion等编写类似的Converter public class ColorConverter : JsonConverterColor { public override void WriteJson(JsonWriter writer, Color value, JsonSerializer serializer) { writer.WriteStartObject(); writer.WritePropertyName(r); writer.WriteValue(value.r); writer.WritePropertyName(g); writer.WriteValue(value.g); writer.WritePropertyName(b); writer.WriteValue(value.b); writer.WritePropertyName(a); writer.WriteValue(value.a); writer.WriteEndObject(); } public override Color ReadJson(JsonReader reader, Type objectType, Color existingValue, bool hasExistingValue, JsonSerializer serializer) { JObject obj JObject.Load(reader); return new Color( obj[r]?.Valuefloat() ?? 0, obj[g]?.Valuefloat() ?? 0, obj[b]?.Valuefloat() ?? 0, obj[a]?.Valuefloat() ?? 1 ); } }如何使用Converter有两种方式通过属性标记推荐用于特定字段public class TransformData { [JsonConverter(typeof(Vector3Converter))] public Vector3 Position; [JsonConverter(typeof(QuaternionConverter))] // 需要你实现QuaternionConverter public Quaternion Rotation; }通过全局Settings添加适用于整个项目JsonSerializerSettings settings new JsonSerializerSettings(); settings.Converters.Add(new Vector3Converter()); settings.Converters.Add(new ColorConverter()); // ... 添加其他Converter4.2 多态序列化处理继承和接口这是JsonUtility的致命弱点却是Newtonsoft.Json的强项。假设你有一个基类Shape和两个子类Circle、Rectangle你想序列化一个ListShape并能在反序列化时恢复正确的类型。[JsonConverter(typeof(JsonSubtypes), Type)] // 使用第三方库JsonSubtypes简化或手动实现 public abstract class Shape { public abstract string Type { get; } public string Name; } public class Circle : Shape { public override string Type Circle; public float Radius; } public class Rectangle : Shape { public override string Type Rectangle; public float Width; public float Height; }使用Newtonsoft.Json原生方案TypeNameHandlingvar settings new JsonSerializerSettings { TypeNameHandling TypeNameHandling.Auto, // 或 All, Objects, Arrays // Formatting Formatting.Indented }; ListShape shapes new ListShape { new Circle { Name MyCircle, Radius 5 }, new Rectangle { Name MyRect, Width2, Height3 } }; string json JsonConvert.SerializeObject(shapes, settings); Debug.Log(json); // JSON中会包含 $type 字段指示具体类型例如 // [{$type:YourNamespace.Circle, YourAssembly,Radius:5.0,Name:MyCircle}, ...] ListShape deserializedShapes JsonConvert.DeserializeObjectListShape(json, settings); // deserializedShapes[0] 将是 Circle 类型重要安全警告TypeNameHandling是一个强大的功能但也是一个潜在的安全风险。如果反序列化的JSON来自不可信的源如网络请求攻击者可能在$type字段中注入恶意类型名导致意外的类型实例化甚至代码执行。因此在反序列化用户输入时绝对不要使用TypeNameHandling.All或TypeNameHandling.Auto。应使用TypeNameHandling.None或通过自定义BinderSerializationBinder来严格限制允许反序列化的类型白名单。4.3 性能优化策略JSON序列化在频繁操作如每帧处理网络消息时可能成为性能瓶颈。缓存JsonSerializerSettings和JsonSerializer不要每次序列化都new一个。创建静态的单例或池来重用它们。JsonSerializer的创建开销相对较大。public static class JsonSerializerCache { private static readonly JsonSerializerSettings _cachedSettings CreateSettings(); private static readonly JsonSerializer _cachedSerializer JsonSerializer.CreateDefault(_cachedSettings); public static JsonSerializerSettings Settings _cachedSettings; public static JsonSerializer Serializer _cachedSerializer; private static JsonSerializerSettings CreateSettings() { ... } }使用流式API处理大JSON对于巨大的JSON文件如配置表不要一次性读入内存再反序列化。使用JsonTextReader进行流式读取。using (StreamReader file File.OpenText(huge.json)) using (JsonTextReader reader new JsonTextReader(file)) { while (reader.Read()) { if (reader.TokenType JsonToken.StartObject) { // 手动读取对象属性或反序列化单个对象 JObject obj JObject.Load(reader); // 处理obj... } } }为高频类型定制合约解析器ContractResolver通过实现IContractResolver你可以预先计算好某个类型的序列化/反序列化“蓝图”JsonContract避免每次操作都进行反射。对于性能要求极高的场景这是终极优化手段但实现复杂度较高。在IL2CPP下考虑AOT预编译如果即使有了link.xml在特定设备上仍遇到ExecutionEngineException特别是涉及泛型序列化时你可能需要更激进的手段——为用到的泛型类型显式创建代码引用迫使AOT编译器生成对应代码。这通常通过一个“预置”脚本来实现// AOTGenericsPreserver.cs // 这个类里的代码不会真正执行但它的存在会让AOT编译器为列出的泛型类型生成代码 public class AOTGenericsPreserver { // 强迫编译器为 Newtonsoft.Json 序列化 ListT 和 DictionaryTKey, TValue 生成代码 private void PreserveGenerics() { // 你的数据模型中用到的具体泛型类型 var list1 new Listint(); var list2 new Liststring(); var list3 new ListMyDataClass(); var dict1 new Dictionarystring, int(); var dict2 new Dictionaryint, MyDataClass(); // 强迫Newtonsoft.Json为这些类型生成序列化代码 JsonConvert.SerializeObject(list1); JsonConvert.SerializeObject(list2); JsonConvert.SerializeObject(dict1); // ... 添加所有可能用到的类型 } }将这个脚本放在项目中确保它被编译。在构建时IL2CPP会看到这些代码路径从而为相关类型生成AOT代码。5. 实战场景与疑难问题排查5.1 场景游戏存档与读档这是一个典型应用。你需要序列化整个游戏状态可能包含玩家数据、关卡进度、物品库存等。[System.Serializable] public class GameSaveData { public string SaveVersion 1.0; public DateTime SaveTime; public PlayerData Player; public ListInventoryItem Inventory; public Dictionarystring, LevelProgress LevelProgressMap; // JsonUtility不支持但Newtonsoft.Json支持 public SettingsData Settings; // 使用自定义转换器处理Unity类型 [JsonConverter(typeof(Vector3Converter))] public Vector3 LastCheckpoint; // 忽略临时或计算字段 [JsonIgnore] public bool IsLoadedFromCloud; } public static class SaveSystem { private static JsonSerializerSettings _saveSettings; static SaveSystem() { _saveSettings new JsonSerializerSettings { Formatting Formatting.Indented, ReferenceLoopHandling ReferenceLoopHandling.Ignore, TypeNameHandling TypeNameHandling.None, // 存档数据通常不需要多态 ContractResolver new CamelCasePropertyNamesContractResolver(), // 使用驼峰命名与许多前端约定一致 Converters { new Vector3Converter(), new ColorConverter() } }; } public static void SaveGame(string savePath, GameSaveData data) { string json JsonConvert.SerializeObject(data, _saveSettings); File.WriteAllText(savePath, json); // 可选加密json字符串后再存储 } public static GameSaveData LoadGame(string savePath) { if (!File.Exists(savePath)) return null; string json File.ReadAllText(savePath); // 可选解密json字符串 try { return JsonConvert.DeserializeObjectGameSaveData(json, _saveSettings); } catch (JsonException ex) { Debug.LogError($存档文件损坏: {ex.Message}); return null; } } }5.2 场景与Web API通信如RESTful API处理网络请求和响应是JSON的另一大主战场。你需要处理日期格式、枚举字符串、可能为null的字段等。public class ApiResponseT { public int Code { get; set; } public string Message { get; set; } public T Data { get; set; } } public class UserInfo { [JsonProperty(user_id)] // 映射JSON中的蛇形命名 public int UserId { get; set; } [JsonProperty(user_name)] public string UserName { get; set; } [JsonProperty(created_at)] public DateTime CreatedAt { get; set; } [JsonProperty(status)] [JsonConverter(typeof(StringEnumConverter))] // 将枚举序列化为字符串 public UserStatus Status { get; set; } } public static class ApiSerializer { private static readonly JsonSerializerSettings _apiSettings; static ApiSerializer() { _apiSettings new JsonSerializerSettings { NullValueHandling NullValueHandling.Ignore, DateFormatString yyyy-MM-ddTHH:mm:ssZ, // ISO 8601格式 ContractResolver new DefaultContractResolver { NamingStrategy new SnakeCaseNamingStrategy() // 全局蛇形命名 }, Converters { new StringEnumConverter() } }; } public static string SerializeRequestT(T request) { return JsonConvert.SerializeObject(request, _apiSettings); } public static ApiResponseT DeserializeResponseT(string json) { return JsonConvert.DeserializeObjectApiResponseT(json, _apiSettings); } }5.3 常见问题排查表问题现象可能原因解决方案IL2CPP构建后崩溃错误信息包含ExecutionEngineException或MissingMethodException。代码裁剪器移除了Newtonsoft.Json通过反射调用的方法。1. 确保存在并正确配置了Assets/link.xml文件。2. 检查是否所有通过JSON序列化的自定义类型都在link.xml中保留。3. 考虑实现AOTGenericsPreserver为泛型类型预生成代码。序列化/反序列化非常慢尤其在移动设备上。1. 频繁创建JsonSerializerSettings。2. 序列化极其复杂的对象图。3. 使用了大量自定义JsonConverter且实现低效。1. 缓存JsonSerializerSettings和JsonSerializer实例。2. 优化数据模型避免过度嵌套和循环引用。3. 审查自定义Converter的性能避免在ReadJson/WriteJson中频繁创建JToken。反序列化后字段值为null或默认值。1. JSON中的属性名与C#属性/字段名不匹配大小写、命名风格。2. 字段是只读的没有setter。3. 使用了NullValueHandling.Ignore但期望字段在JSON缺失时保持原有值。1. 使用[JsonProperty(json_name)]属性显式指定映射。2. 为属性添加set;或使用[JsonConstructor]标记自定义构造函数。3. 反序列化时使用JsonSerializer.Populate来更新现有对象而非创建新对象。循环引用导致堆栈溢出或数据膨胀。对象A引用BB又引用A形成循环。在JsonSerializerSettings中设置ReferenceLoopHandling ReferenceLoopHandling.Ignore或ReferenceLoopHandling.Serialize后者会序列化引用ID。更好的方法是重新设计数据模型打破不必要的循环引用。Dictionary的Key不是字符串时序列化结果奇怪。Newtonsoft.Json默认将非字符串Key序列化为Key: Value格式但反序列化时可能无法正确还原。1. 尽量使用string作为Key。2. 为特定的Key类型如Enum编写自定义的JsonConverter。3. 使用[JsonDictionary]属性进行更精细的控制需要较新版本。在WebGL平台上报错或功能异常。WebGL环境下的.NET支持是子集且线程模型不同。1. 确保使用支持.NET Standard 2.0的Newtonsoft.Json版本官方UPM包满足。2. 避免在JSON序列化中使用System.Threading相关代码因为WebGL是单线程的。3. 测试时使用WebGL的Development Build查看Console中的详细错误。与其他插件冲突出现TypeLoadException或FileLoadException。多个插件都自带了不同版本的Newtonsoft.Json.dll。1.最佳实践统一使用UPM包管理Newtonsoft.Json并强制其他插件使用该版本。在Assets根目录创建csc.rsp文件内容为-r:Newtonsoft.Json.dll并确保插件目录没有自带版本的DLL。2. 使用 Assembly Version Unification 如果插件是源码形式。3. 联系插件作者请求其支持UPM依赖或提供不含Newtonsoft.Json的版本。6. 进阶自定义合约解析器ContractResolver实战当你需要对序列化过程进行深度控制时IContractResolver是你的终极武器。例如你想实现基于属性的动态序列化如根据用户权限决定序列化哪些字段或者想改变所有DateTime的序列化格式。下面是一个示例创建一个合约解析器自动将C#的PascalCase属性名序列化为JSON的camelCase并且忽略所有标记了[NonSerialized]特性的字段Unity原生特性Newtonsoft.Json默认不认。using System.Reflection; using Newtonsoft.Json; using Newtonsoft.Json.Serialization; using UnityEngine; public class UnityAwareContractResolver : DefaultContractResolver { protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization) { JsonProperty property base.CreateProperty(member, memberSerialization); // 1. 应用camelCase命名 property.PropertyName GetCamelCaseName(property.PropertyName); // 2. 忽略标记了[NonSerialized]的字段 if (member is FieldInfo fieldInfo) { if (fieldInfo.IsDefined(typeof(NonSerializedAttribute), true)) { property.Ignored true; } } // 3. 可选忽略所有私有字段除非有[JsonProperty]标记 if (member is FieldInfo fi fi.IsPrivate !member.IsDefined(typeof(JsonPropertyAttribute), true)) { property.Ignored true; } // 4. 可选为特定类型如Vector3动态添加Converter如果未显式标记 if (property.PropertyType typeof(Vector3) property.Converter null) { property.Converter new Vector3Converter(); } return property; } private string GetCamelCaseName(string name) { if (string.IsNullOrEmpty(name) || !char.IsUpper(name[0])) return name; return char.ToLowerInvariant(name[0]) name.Substring(1); } // 单例模式因为ContractResolver应该是无状态的且可重用的 private static UnityAwareContractResolver _instance; public static UnityAwareContractResolver Instance _instance ?? new UnityAwareContractResolver(); } // 使用方式 var settings new JsonSerializerSettings { ContractResolver UnityAwareContractResolver.Instance, Formatting Formatting.Indented };这个自定义解析器在创建每个属性的序列化契约时被调用让你有机会修改其名称、是否忽略、用什么转换器等属性。它非常强大但也会对性能有轻微影响因为每个类型在第一次序列化时需要构建这个契约。因此务必像示例中一样将其作为单例缓存起来。7. 版本管理与未来展望版本管理时刻关注你使用的Newtonsoft.Json版本。如果你通过UPM使用com.unity.nuget.newtonsoft-json定期检查Package Manager是否有更新。虽然官方不提供支持但更新可能包含重要的安全修复或性能改进。在升级前务必在独立分支或测试项目中进行全面测试因为大版本更新如从12.x到13.x可能有破坏性变更。替代方案展望虽然Newtonsoft.Json目前仍是Unity社区处理复杂JSON的事实标准但也要了解其他选项。System.Text.Json在纯.NET环境下的性能优势明显随着Unity对.NET现代版本支持度的提升它可能成为未来的选择。对于极度追求性能的场景可以考虑像MemoryPack或MessagePack这样的二进制序列化方案它们比JSON更小更快但牺牲了人类可读性。最后的建议将你的JSON序列化逻辑封装在一个独立的服务类或静态工具类中。不要在你的游戏逻辑代码中到处散落JsonConvert.SerializeObject。集中管理JsonSerializerSettings、自定义转换器、错误处理try-catch和日志记录。这样不仅代码更整洁当未来需要迁移到新的序列化方案时你也只需要改动这一个地方。我在多个大型Unity项目中深度应用了这套基于Newtonsoft.Json的适配方案它帮我处理了从简单的配置表到复杂的网络协议、从本地存档到云端数据同步的各种需求。其稳定性和灵活性从未让我失望。关键在于理解其原理做好IL2CPP的适配并遵循良好的封装实践。希望这篇指南能成为你Unity开发工具箱中一件趁手的利器。