1. 项目概述为什么Unity开发者需要超越JsonUtility如果你在Unity里做过数据序列化JsonUtility大概率是你第一个接触的工具。它简单、免费、开箱即用序列化一个MonoBehaviour的公共字段或者一个[System.Serializable]标记的类几行代码就能搞定。但当你项目稍微深入需要处理字典、处理多态类型、追求极致的性能或者需要与后端复杂的JSON结构无缝对接时JsonUtility的“温柔一刀”就开始让你处处掣肘。比如它不支持Dictionarystring, T的直接序列化处理继承结构时表现笨拙性能在大量数据面前也显得力不从心。这时寻找一个更强大的替代品就成了必然。Utf8Json正是在这种背景下进入Unity开发者视野的。它并非为Unity而生而是一个高性能、零分配的.NET JSON序列化器。其核心优势在于直接操作UTF-8字节避免了字符串中间转换带来的额外开销和GC垃圾回收压力这对于需要每帧处理大量网络数据或配置表的游戏来说是至关重要的性能提升。同时它通过特性Attribute和解析器Resolver提供了极高的灵活性能够优雅地处理复杂对象图、多态序列化等JsonUtility的“禁区”。这个项目就是带你将Utf8Json这套强大的工业级工具无缝、稳定地集成到Unity项目中构建一个从编辑器工具到运行时逻辑都能使用的完整JSON解决方案。2. 核心痛点解析JsonUtility的局限性到底在哪在引入新方案前我们必须彻底弄清楚现有工具的短板这样才能有的放矢。JsonUtility的局限性并非设计失误而是其设计目标简单、轻量所带来的必然结果。2.1 类型支持严重不足这是最直观的痛点。JsonUtility基于Unity的序列化系统因此它只支持Unity序列化系统所支持的类型。这直接导致了许多常用数据结构无法直接使用。不支持字典 (DictionaryTKey, TValue): 游戏开发中用字典根据ID索引配置数据是再常见不过的需求。JsonUtility对此无能为力你不得不将其转换为两个List或者自己实现一个包装类徒增复杂度。多态序列化支持薄弱: 如果你有一个Animal基类数组里面存放着Dog和Cat的实例JsonUtility在反序列化时无法恢复具体的子类型所有对象都会被反序列化为基类Animal丢失了子类的特有数据。虽然可以通过一些奇技淫巧如包装类部分解决但既不优雅也容易出错。对interface、abstract class支持不友好: 与多态问题类似这些类型难以直接被序列化和反序列化。忽略私有字段和属性: 除非标记为[SerializeField]否则私有字段和属性不会被处理。有时我们希望对某些属性进行序列化但不希望它在Inspector中公开JsonUtility的规则就显得不够灵活。2.2 性能与GC分配问题JsonUtility在序列化时内部会将对象转换为JSON字符串反序列化时也是从字符串开始解析。在C#中字符串是UTF-16编码的。这个“对象→JSON字符串→对象”的过程会产生大量的临时字符串进而引发GC分配。在移动平台频繁的GC会触发垃圾回收可能导致帧率卡顿这是游戏性能优化中需要极力避免的。Utf8Json直接读写UTF-8字节数组省去了字符串转换环节从根源上减少了分配。2.3 灵活性与扩展性欠缺JsonUtility的API非常固定你很难干预其序列化和反序列化的过程。自定义命名困难: 后端返回的JSON字段名可能是snake_case而你的C#代码规范是PascalCaseJsonUtility无法直接映射。忽略特定字段: 除了使用[NonSerialized]这也会影响Unity编辑器序列化没有更细粒度的控制方式。处理循环引用: 对象图中存在循环引用时JsonUtility会直接抛出异常而成熟的序列化库通常提供忽略或处理循环引用的选项。日期时间格式: JSON标准中没有日期类型通常用字符串表示。JsonUtility对DateTime的格式处理比较固定难以适配各种后端API的日期格式。注意不要因为JsonUtility有这些限制就全盘否定它。对于简单的、仅在编辑器阶段使用的数据存储比如存储一些工具配置或者序列化非常简单的ScriptableObjectJsonUtility因其无需额外依赖、完全集成在Unity中的特点依然是方便快捷的选择。我们的目标是建立一个分层的解决方案简单场景用JsonUtility复杂、高性能场景用Utf8Json。3. Utf8Json核心优势与在Unity中的适配Utf8Json的设计哲学是“极速”与“零分配”。它通过预编译的表达式树生成针对特定类型的、高度优化的序列化/反序列化代码避免了运行时反射带来的开销。其核心工作流程是直接与byte[]和IBufferWriterbyte交互。3.1 核心优势详解极致性能直接操作UTF-8字节避免了string的转换和分配。在官方基准测试中其性能通常是Newtonsoft.Json另一个流行库的2-10倍GC分配更是少得多。强大的类型系统支持原生支持字典、集合、多态序列化通过[JsonFormatter(typeof(SomeFormatter))]或Union特性、元组等。高扩展性通过实现IJsonFormatterT接口你可以为任何类型定制序列化逻辑。通过IJsonFormatterResolver解析器你可以组合不同的格式化规则例如处理C#的PascalCase属性名与JSON的camelCase字段名之间的映射。流式API支持Utf8JsonReader和Utf8JsonWriter进行手动、低级别的JSON读写为你处理非标准或超大JSON数据提供了可能。3.2 Unity环境下的特殊适配将通用的.NET库引入Unity需要特别注意一些平台差异和Unity自身的生命周期。IL2CPP与代码裁剪Code Stripping这是最大的挑战。Utf8Json依赖运行时反射或表达式树来生成格式化器。在IL2CPP构建中尤其是开启了代码裁剪后未被显式引用的类型和方法可能被移除导致运行时出现JsonParsingException或FormatterNotRegisteredException。解决方案是使用“预编译”或“AOT生成”。Utf8Json提供了Utf8Json.UniversalCodeGenerator工具可以预先为你的项目中的所有类型生成格式化器代码从而完全避免运行时反射。Unity版本与.NET兼容性确保你使用的Utf8Json版本与你Unity项目设置的.NET API兼容性级别如.NET Standard 2.0, .NET 4.x匹配。通常以.NET Standard 2.0为目标的版本在Unity中兼容性最好。异步支持Unity旧版本2021.2之前的.NET运行时对System.Text.Json的异步流支持不完整但Utf8Json自身的异步API通常基于Stream在Unity WebGL等平台需要测试。对于大多数游戏内场景同步API已足够。源码集成 vs DLL为了避免平台依赖问题推荐将Utf8Json的源码C#文件直接放入你的Unity项目的Plugins或ThirdParty目录中。这样可以确保它被Unity编译器正确编译并受益于Unity的脚本编译后端处理。实操心得在项目初期就决定是否使用预生成AOT。对于中小型项目可能不需要。但对于大型项目或要求稳定的发布版本强烈建议在CI/CD流程中加入预生成格式化器这一步这能彻底消除IL2CPP下的不确定性。4. 完整集成方案从导入到最佳实践4.1 导入与基础配置获取Utf8Json从GitHub发布页下载源码包如utf8json-master.zip。不建议直接使用NuGet包因为Unity的包管理器处理NuGet有时会复杂。放置源码在Unity项目的Assets文件夹下创建一个ThirdParty/Utf8Json目录将下载的源码中src/Utf8Json和src/Utf8Json.UnityClient如果存在或src/Utf8Json.Aot等必要的文件夹复制进去。确保主要代码文件位于Assets目录下能被编译。基础使用现在你就可以在代码中使用Utf8Json.JsonSerializer.SerializeT和DeserializeT了。using Utf8Json; public class PlayerData { public string Name { get; set; } public int Level { get; set; } public Dictionarystring, int Inventory { get; set; } // JsonUtility不支持的字典 } // 序列化 PlayerData data new PlayerData { Name Hero, Level 10, Inventory new Dictionarystring, int { { Potion, 5 } } }; byte[] jsonBytes JsonSerializer.Serialize(data); // 可以将byte[]转换为string查看但实际传输存储应用byte[] string jsonString Encoding.UTF8.GetString(jsonBytes); // 反序列化 byte[] receivedBytes ... // 从网络或文件读取 PlayerData deserializedData JsonSerializer.DeserializePlayerData(receivedBytes);4.2 配置解析器Resolver实现命名约定默认情况下Utf8Json保持属性名原样。为了与常见的JSONcamelCase约定兼容我们需要配置并使用一个解析器。使用内置解析器Utf8Json提供了StandardResolver的变体如StandardResolver.CamelCase。var options JsonSerializer.DefaultResolver; // 更常用的方式是直接在序列化时指定 byte[] bytes JsonSerializer.Serialize(data, StandardResolver.CamelCase); PlayerData data JsonSerializer.DeserializePlayerData(bytes, StandardResolver.CamelCase);创建自定义解析器更灵活你可以组合多个解析器并加入自己的规则。// 创建一个复合解析器优先使用特性Attribute然后使用CamelCase最后使用默认 public class MyCustomResolver : IJsonFormatterResolver { public static IJsonFormatterResolver Instance new MyCustomResolver(); private MyCustomResolver() {} public IJsonFormatterT GetFormatterT() FormatterCacheT.formatter; private static class FormatterCacheT { public static readonly IJsonFormatterT formatter; static FormatterCache() { // 这里可以组合多个解析器 formatter (IJsonFormatterT)Utf8Json.Resolvers.CompositeResolver.Create( new IJsonFormatter[] { // 为特定类型注册自定义格式化器例如处理特殊的DateTime格式 new MyDateTimeFormatter() }, new IJsonFormatterResolver[] { Utf8Json.Resolvers.AttributeFormatterResolver.Instance, // 优先使用[JsonFormatter]特性 Utf8Json.Resolvers.StandardResolver.CamelCase // 使用驼峰命名 }); } } } // 使用时 JsonSerializer.Serialize(data, MyCustomResolver.Instance);4.3 处理多态类型继承与接口这是Utf8Json相比JsonUtility的一大亮点。这里介绍两种主流方法方法一使用Union特性推荐用于明确的类型集合[JsonFormatter(typeof(JsonUnionFormatterAnimal))] // 在基类上标记 public abstract class Animal { public string Name { get; set; } } // 使用Union特性注册子类型并指定键 [Union(0, typeof(Dog))] [Union(1, typeof(Cat))] public class Dog : Animal { public int BarkVolume { get; set; } } public class Cat : Animal { public bool IsLazy { get; set; } } // 序列化后JSON中会包含一个类型鉴别字段如$type:0反序列化时能正确还原为Dog或Cat。 ListAnimal zoo new ListAnimal { new Dog(), new Cat() }; var bytes JsonSerializer.Serialize(zoo, MyCustomResolver.Instance); // 必须使用包含AttributeFormatterResolver的解析器方法二实现自定义IJsonFormatterT更灵活控制当类型鉴别逻辑更复杂或者你不希望修改原有类定义时可以为基类或接口实现一个自定义格式化器。public class AnimalFormatter : IJsonFormatterAnimal { public void Serialize(ref JsonWriter writer, Animal value, IJsonFormatterResolver formatterResolver) { if (value null) { writer.WriteNull(); return; } writer.WriteBeginObject(); // 写入类型标识 writer.WritePropertyName(type); writer.WriteString(value.GetType().Name); // 写入实际数据 writer.WriteValueSeparator(); writer.WritePropertyName(data); // 根据具体类型使用对应的格式化器序列化数据部分 if (value is Dog dog) { formatterResolver.GetFormatterDog().Serialize(ref writer, dog, formatterResolver); } else if (value is Cat cat) { formatterResolver.GetFormatterCat().Serialize(ref writer, cat, formatterResolver); } writer.WriteEndObject(); } public Animal Deserialize(ref JsonReader reader, IJsonFormatterResolver formatterResolver) { // 读取JSON对象解析“type”字段然后根据类型调用对应的格式化器反序列化“data”部分 // ... 具体实现略需要处理JSON读取的细节 } } // 然后通过自定义解析器注册这个AnimalFormatter。4.4 AOT预编译解决IL2CPP问题这是保证项目在发布到iOS、Android、WebGL等平台稳定运行的关键步骤。定位生成工具在Utf8Json源码中找到Utf8Json.UniversalCodeGenerator项目通常是一个控制台应用。编译生成器使用你本地安装的.NET SDK如.NET 6编译这个项目生成一个可执行文件。准备目标程序集将你的Unity项目中所有包含需要序列化类型的C#程序集通常是Assembly-CSharp.dll以及你自定义的程序集复制到一个临时目录。你可以在Unity编辑器菜单栏执行File - Build Settings - Player Settings - Publishing Settings下勾选Create Visual Studio Solution或使用Assembly Definition Files来组织清晰的程序集结构便于定位。执行生成命令# 示例命令 UniversalCodeGenerator.exe --inputpath/to/your/Assembly-CSharp.dll --outputAssets/Scripts/Generated/Utf8JsonGeneratedFormatter.cs --resolverYourNamespace.YourCustomResolver这个命令会分析你的DLL为所有被使用的可序列化类型生成格式化器代码并输出到一个单一的C#文件中。将生成的文件放入Unity将生成的.cs文件放入Unity项目的Assets目录下如Assets/Generated/确保它被编译。生成的代码会静态注册所有格式化器。在自定义解析器中引用生成的解析器你需要修改你的自定义解析器将生成的解析器通常名为GeneratedResolver加入到解析器链中。// 在CompositeResolver.Create中加入生成的解析器 formatter (IJsonFormatterT)Utf8Json.Resolvers.CompositeResolver.Create( new IJsonFormatter[] { /* 自定义格式化器 */ }, new IJsonFormatterResolver[] { Utf8Json.Resolvers.AttributeFormatterResolver.Instance, Utf8Json.Resolvers.GeneratedResolver.Instance, // 这是AOT生成的解析器 Utf8Json.Resolvers.StandardResolver.CamelCase });重要提示每次增删改需要序列化的类后都需要重新运行AOT生成步骤以确保生成的格式化器是最新的。可以将此步骤集成到你的项目构建脚本如Jenkins、GitLab CI中自动化执行。5. 实战场景与性能对比5.1 场景一网络数据包序列化在MMO游戏或实时对战游戏中客户端与服务器之间频繁交换数据包。使用Utf8Json可以显著降低GC压力。// 定义协议类 [MessagePackObject] // Utf8Json也支持类似MessagePack的紧凑格式特性但这里我们用JSON public class MovePacket { [Key(0)] // 可以使用Key特性指定顺序使JSON更紧凑 public int PlayerId { get; set; } [Key(1)] public Vector3 Position { get; set; } // 需要为Unity的Vector3编写或注册自定义格式化器 [Key(2)] public float Timestamp { get; set; } } // 发送前序列化 MovePacket packet new MovePacket { PlayerId 1001, Position transform.position, Timestamp Time.time }; byte[] sendData JsonSerializer.Serialize(packet, MyCustomResolver.Instance); networkStream.Write(sendData, 0, sendData.Length); // 示例 // 接收后反序列化 byte[] receiveBuffer new byte[1024]; int bytesRead networkStream.Read(receiveBuffer, 0, receiveBuffer.Length); MovePacket receivedPacket JsonSerializer.DeserializeMovePacket(receiveBuffer.AsSpan(0, bytesRead), MyCustomResolver.Instance); transform.position receivedPacket.Position;性能对比假设一个数据包500字节每秒发送20次。使用JsonUtility通过string中转每次会产生约1KB的临时字符串分配序列化和反序列化各一次每秒产生约20KB的GC分配。而Utf8Json直接操作byte[]分配几乎可以忽略不计主要在byte[]池的租用和归还如果使用ArrayPool则更优。5.2 场景二本地化配置表或存档游戏有大量的配置表如物品、技能、关卡通常由策划在Excel中编辑然后导出为JSON。使用Utf8Json反序列化这些配置到内存中的字典或列表速度更快。// 从StreamingAssets或PersistentDataPath读取配置 string configPath Path.Combine(Application.streamingAssetsPath, ItemConfig.json); byte[] jsonBytes; #if UNITY_ANDROID !UNITY_EDITOR // Android上StreamingAssets需要特殊读取 using (UnityWebRequest request UnityWebRequest.Get(configPath)) { request.SendWebRequest(); while (!request.isDone) yield return null; jsonBytes request.downloadHandler.data; } #else jsonBytes File.ReadAllBytes(configPath); #endif // 反序列化 ListItemConfig itemConfigs JsonSerializer.DeserializeListItemConfig(jsonBytes, MyCustomResolver.Instance); // 转换为字典便于查询 Dictionaryint, ItemConfig itemDict itemConfigs.ToDictionary(x x.Id);对于玩家存档也可以使用Utf8Json序列化整个游戏状态对象相比JsonUtility它能更好地处理复杂的对象关系和集合。5.3 性能测试数据参考以下是一个简单的性能对比在Unity Editor .NET 4.x环境下测试一个包含基础类型、字符串、字典和列表的复杂对象循环10000次序列化速度Utf8Json 比 JsonUtility 快约3-5倍。反序列化速度Utf8Json 比 JsonUtility 快约2-4倍。GC分配关键指标Utf8Json 每次操作分配几十到几百字节主要来自小的byte[]或对象创建而 JsonUtility 由于字符串转换每次操作分配几千字节。在频繁操作下这个差异会被急剧放大。6. 常见问题、排查技巧与优化建议6.1 编译错误与运行时异常错误The type ‘…’ cannot be serialized because it does not have a formatter.原因IL2CPP构建后该类型的格式化器未被正确注册。最常见的原因是未进行AOT预编译或者预编译未覆盖到此类型。解决确保执行了AOT预编译步骤并且生成的文件包含了所有需要的类型。检查你的自定义解析器CompositeResolver.Create是否包含了GeneratedResolver.Instance。对于泛型类型如ListYourClass确保YourClass本身有格式化器。AOT生成器通常能处理封闭构造的泛型。错误JsonParsingException: expected:‘{‘ actual:’\’或其他解析错误原因字节数据不是有效的UTF-8 JSON或者反序列化的目标类型与JSON结构不匹配。排查将出错的byte[]用Encoding.UTF8.GetString(bytes)转换成字符串打印出来用在线JSON验证器检查格式。检查序列化和反序列化时使用的Resolver是否一致。不一致可能导致命名规则CamelCase vs PascalCase对不上。检查JSON字符串中是否包含BOM字节顺序标记某些编辑器保存的UTF-8文件可能带BOM需要手动去除。Unity Editor运行正常打包后IL2CPP崩溃原因几乎可以肯定是AOT问题。解决严格按照第4.4节进行AOT预编译。并确保打包时生成的格式化器代码文件被包含在构建中。6.2 自定义类型格式化器编写要点当你需要为UnityEngine.Vector3、Quaternion或你自己的复杂结构编写格式化器时public class Vector3Formatter : IJsonFormatterVector3 { public void Serialize(ref JsonWriter writer, Vector3 value, IJsonFormatterResolver formatterResolver) { // 写成数组格式 [x, y, z]比对象格式更紧凑 writer.WriteBeginArray(); writer.WriteSingle(value.x); writer.WriteValueSeparator(); writer.WriteSingle(value.y); writer.WriteValueSeparator(); writer.WriteSingle(value.z); writer.WriteEndArray(); } public Vector3 Deserialize(ref JsonReader reader, IJsonFormatterResolver formatterResolver) { // 读取必须与写入格式严格对应 if (reader.ReadIsNull()) return default; reader.ReadIsBeginArrayWithVerify(); // 验证开始符是[ var x reader.ReadSingle(); reader.ReadIsValueSeparatorWithVerify(); // 验证分隔符是, var y reader.ReadSingle(); reader.ReadIsValueSeparatorWithVerify(); var z reader.ReadSingle(); reader.ReadIsEndArrayWithVerify(); // 验证结束符是] return new Vector3(x, y, z); } } // 然后通过自定义解析器注册这个格式化器。关键点Serialize和Deserialize的读写顺序和结构必须完全镜像。使用WithVerify后缀的方法可以在开发时帮助捕获格式错误。6.3 高级优化建议复用缓冲区对于高频调用的序列化如每帧的网络消息可以考虑复用byte[]缓冲区或使用ArrayPoolbyte.Shared来租用数组进一步减少GC。private static readonly ArrayPoolbyte BytePool ArrayPoolbyte.Shared; public byte[] SerializeReusableT(T obj) { var writer new JsonWriter(); // JsonWriter内部有缓冲区 JsonSerializer.Serialize(ref writer, obj, MyCustomResolver.Instance); var rentedBuffer BytePool.Rent(writer.ToBuffer().Count); // 根据实际大小租用 try { // ... 复制数据到rentedBuffer ... return rentedBuffer; // 注意调用方需要归还到池中 } finally { BytePool.Return(rentedBuffer); } }使用MemoryT/SpanTAPIUtf8Json支持最新的内存类型。如果你的项目使用较新的.NET版本利用Spanbyte可以避免不必要的数组拷贝。选择性序列化使用[IgnoreDataMember]特性或在自定义格式化器中控制哪些字段需要序列化减少不必要的数据传输和存储。版本兼容性为你的数据类添加[DataContract]和[DataMember(Order N)]特性可以为字段指定顺序。这样即使类结构发生变化如添加新字段旧版本序列化的数据在反序列化时只有顺序匹配的字段会被读取提高了前后版本数据文件的兼容性。集成Utf8Json到Unity项目初期会有些配置成本尤其是处理AOT预编译。但一旦搭建完成它将为你提供一个高性能、高灵活性、类型安全的JSON处理管道彻底释放你在处理复杂数据时的生产力并为你的游戏性能表现带来实实在在的收益。从JsonUtility迁移过来最需要改变的是思维习惯从“字符串中心”转向“字节中心”并善用其强大的扩展机制来应对各种复杂场景。
