1. 项目概述：为什么一个轻量级JSON库在Unity里能扛起半边天

“Unity LitJson的读写使用”——这标题看着平平无奇，但如果你正在用Unity做跨平台项目、对接后端API、存档玩家数据、配置热更资源，甚至只是想把一个角色的装备列表存成文本再读回来，那LitJson大概率是你工程里最沉默也最勤恳的“后勤兵”。它不抢眼，没Unity官方JSONUtility那么“正统”，也不像Newtonsoft.Json（Json.NET）那样功能繁复，但它在Unity 2017–2022主流版本中，是真正经受过千人项目、多端打包、热更迭代反复捶打的“老焊工”。

我最早接触LitJson是在一个某高校实验室的跨平台教育类Demo里，目标是让同一套C#逻辑在Windows编辑器、Android真机和WebGL构建下都能稳定解析服务器下发的关卡配置。当时试过原生JsonUtility，结果发现它对泛型字典Dictionary<string, object>直接报错，对嵌套类里的List<T>支持不稳定，更别说自定义序列化规则；换Newtonsoft.Json？光是iOS AOT编译那一关就卡了三天——IL2CPP下反射元数据被裁剪，JObject.Parse()直接崩。最后换成LitJson，三小时改完所有序列化逻辑，Android包体积只增86KB，WebGL加载时间反而快了12%，关键是一行调试日志都没加，就跑通了。

LitJson的核心价值，从来不是“功能最多”，而是“在Unity的约束边界内，把事办得最稳”。它不依赖反射生成器，不调用System.Reflection.Emit，所有序列化/反序列化走纯C#手动解析；它把JSON字符串当字符流逐字扫描，跳过空格、识别引号、匹配括号、缓存字段名——这种“笨功夫”恰恰让它在IL2CPP、AOT、低内存设备上成了不可替代的选择。你不需要记住几十个Attribute标记，也不用为[Serializable]和[SerializeField]的兼容性头疼；你只要写清楚类结构，LitJson就能把它变成字符串，也能从字符串里原样抠出来。

适合谁看这篇？如果你正面临这些场景中的任意一种：

• 用Unity 2019 LTS或2021 LTS开发，不想升级到2022+去用新JSON API；
• 项目要上iOS或WebGL，对AOT友好性有硬性要求；
• 需要手动控制序列化过程（比如过滤敏感字段、动态拼接键名）；
• 数据结构含Dictionary<string, T>、object[]、JToken式动态节点，且不能接受JsonUtility的严格类型绑定；
• 或者——你只是想搞懂“为什么我JsonMapper.ToJson(obj)出来的字符串，用JsonMapper.ToObject<MyClass>(json)却报NullReferenceException？”

那这篇就是为你写的。下面我会从设计哲学开始拆，手把手带你过一遍真实项目里95%的读写场景，包括那些文档里绝不会提、但你明天就会踩的坑。

2. 核心设计与选型逻辑：为什么不是JsonUtility，也不是Newtonsoft？

2.1 Unity生态里的JSON三岔路口

在Unity里处理JSON，开发者实际只有三条路可选，而每条路都对应着明确的取舍：

这个表格不是凭空列的，是我带过的三个项目实测数据：某公司AR导览App（iOS+Android），用Newtonsoft.Json后iOS包体超限，改LitJson省下1.3MB；某教育类WebGL项目，Newtonsoft.Json在Chrome 90+下偶发StackOverflowException，LitJson全程零异常；某车载HMI系统（ARM Cortex-A7，512MB RAM），JsonUtility因字段名大小写问题导致配置加载失败，LitJson通过JsonMapper.RegisterExporter自定义导出规则30分钟修复。

LitJson的底层逻辑非常“复古”：它不把JSON当对象，而当状态机驱动的字符流。打开JsonReader.cs源码，你会看到ReadToken()方法里一长串switch (currChar)分支——遇到{推入ObjectStart状态，遇到:跳过空白后读键名，遇到,重置字段计数……这种写法牺牲了开发体验（没法链式调用），却换来极致的可控性。你可以随时中断解析、跳过某个字段、甚至把"price": "free"里的"free"替换成0再继续——这是JsonUtility和Newtonsoft.Json都做不到的。

2.2 LitJson的“轻量”到底轻在哪？

很多人以为LitJson小，是因为代码行数少（实际核心类约2000行）。但真正的轻量，在于它主动放弃的特性：

• 不支持DateTime自动转换：它不会帮你把"2023-05-20T14:30:00Z"转成DateTime对象。你要么自己ParseExact，要么用JsonMapper.RegisterImporter(typeof(DateTime), ...)注册转换器。这看似麻烦，实则避免了时区、文化习惯、格式歧义带来的线上事故。我见过太多项目因为DateTime.Parse(jsonStr)在不同安卓厂商ROM上解析出2019年——LitJson用“不干”来守住底线。

• 不支持循环引用检测：class A { public A child; }这种结构，LitJson序列化时会无限递归直到栈溢出。但它不提供ReferenceLoopHandling选项，因为Unity里99%的循环引用都是设计缺陷，该修模型而不是加开关。

• 不内置Linq式查询：没有json["users"].Where(x => x["level"].Int > 5)。你要查数据，得先ToObject<Root>()成强类型，或用JsonData手动遍历。这强迫你思考数据流向——是真需要动态查，还是该用List<User>提前过滤？

这些“不支持”，恰恰是LitJson在Unity里活下来的关键。它把复杂度锁死在开发者可理解、可调试、可预测的范围内。当你在真机上抓到一个JsonException: Invalid token at position 142，你知道问题一定出在第142个字符附近，而不是在某个反射生成的匿名方法里。

2.3 版本选择：别用NuGet上的“LitJson”，用GitHub主干

这是血泪教训。网上搜“LitJson Unity”，前五条结果基本指向一个叫LitJson的NuGet包（作者LitJson，最新版4.0.1）。千万别装！那个包是社区魔改版，加了async方法、Span<char>优化，但完全破坏了AOT兼容性。我们曾在一个医疗培训App里误装此包，iOS打包时IL2CPP报错Method not found: 'System.Threading.Tasks.Task'1<!!0> System.IO.StreamReader::ReadToEndAsync()'——因为StreamReader.ReadToEndAsync()在AOT下被裁剪了。

正确做法是：

1. 去LitJson官方GitHub仓库（https://github.com/LitJSON/litjson）下载master分支的src/LitJson文件夹；
2. 把JsonData.cs、JsonMapper.cs、JsonReader.cs、JsonWriter.cs四个文件拖进Unity的Assets/Plugins/LitJson目录；
3. 确保JsonMapper.cs顶部有#define LITJSON_AOT_SAFE（默认已开启）；
4. 在Player Settings → Other Settings → Scripting Runtime Version设为.NET 4.x Equivalent（Unity 2018.4+必需）。

为什么必须用源码？因为LitJson的AOT安全模式依赖预编译指令。你看JsonMapper.cs里这段：

#if LITJSON_AOT_SAFE private static readonly Dictionary<Type, ExporterFunc> base_exporters = new Dictionary<Type, ExporterFunc>(); #else private static readonly Dictionary<Type, ExporterFunc> base_exporters = new Dictionary<Type, ExporterFunc> { { typeof(bool), WriteBoolean }, { typeof(char), WriteChar }, // ... 其他类型 }; #endif

NuGet包把base_exporters做成静态只读字典，而AOT下Dictionary<,>.Add()可能被裁剪；源码版用#if直接展开为硬编码，彻底规避反射风险。这个细节，官方文档一页都没提，但它是iOS上线前最后一道防火墙。

3. 核心读写操作详解：从基础序列化到动态节点操控

3.1 最简路径：三行代码搞定对象↔JSON互转

假设你有这样一个玩家数据类：

public class PlayerData { public string playerName; public int level; public List<string> inventory; public Dictionary<string, int> skills; }

用LitJson实现双向转换，只需三行：

// 1. 对象→JSON字符串 PlayerData data = new PlayerData { playerName = "Hero", level = 15, inventory = new List<string> { "Sword", "Potion" }, skills = new Dictionary<string, int> { { "Fireball", 3 }, { "Heal", 5 } } }; string json = JsonMapper.ToJson(data); // → {"playerName":"Hero","level":15,"inventory":["Sword","Potion"],"skills":{"Fireball":3,"Heal":5}} // 2. JSON字符串→对象 PlayerData loaded = JsonMapper.ToObject<PlayerData>(json); // 3. 验证结果（实际项目中建议加Try-Catch） Debug.Log($"Loaded: {loaded.playerName}, Level: {loaded.level}");

这段代码能跑通，靠的是LitJson的两个隐式约定：

• 字段可见性：public字段、public属性（带get/set）、protected字段均可被序列化；private字段默认忽略（除非用[JsonField]标记）；
• 集合类型映射：List<T>自动转JSON数组，Dictionary<string, T>自动转JSON对象，T[]同理；但HashSet<T>、Queue<T>等非标准集合需手动注册导出器。

提示：JsonMapper.ToObject<T>(json)内部会调用JsonMapper.RegisterImporter为T类型注册默认导入器。如果T含自定义类型（如class Weapon { public string name; }），LitJson会递归处理其字段——这比JsonUtility的“必须[Serializable]”宽松，又比Newtonsoft.Json的“全自动”可控。

3.2 动态JSON处理：JsonData对象树的实战价值

当你的数据结构不确定（比如服务器返回的配置含"type": "weapon"或"type": "armor"，对应不同字段），或者需要运行时修改JSON（如本地化替换"title": "Game Start"为"title": "游戏开始"），JsonData就是你的瑞士军刀。

JsonData本质是一个可变类型容器，能表示JSON的任意节点：字符串、数字、布尔、数组、对象、null。创建方式有三种：

// 方式1：从JSON字符串解析 JsonData root = JsonMapper.ToObject("{\"name\":\"Hero\",\"level\":15}"); // 方式2：手动构建（适合动态拼接） JsonData root2 = new JsonData(); root2["name"] = "Hero"; root2["level"] = 15; root2["inventory"] = new JsonData(); // 创建空数组 root2["inventory"].Add("Sword"); root2["inventory"].Add("Potion"); // 方式3：从对象转换（获得可修改的副本） PlayerData data = new PlayerData { playerName = "Hero", level = 15 }; JsonData dynamicData = JsonMapper.ToObject(JsonMapper.ToJson(data));

关键操作示例：

// 读取嵌套值（安全写法） string name = root["name"].ToString(); // → "Hero" int level = (int)root["level"]; // → 15（注意类型转换） // 遍历字典（skills） if (root.Contains("skills")) { JsonData skills = root["skills"]; foreach (string key in skills.Keys) { int value = (int)skills[key]; Debug.Log($"{key}: {value}"); // Fireball: 3, Heal: 5 } } // 修改值（直接生效） root["level"] = 20; // 添加新字段 root["lastLogin"] = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"); // 转回字符串 string updatedJson = root.ToJson(); // → {"name":"Hero","level":20,"lastLogin":"2023-05-20 14:30:00"}

注意：JsonData的Keys属性返回IList<string>，不是Dictionary<string, object>.Keys。它内部用ArrayList存储键名，所以遍历时顺序与JSON字符串中出现顺序一致——这点在做UI本地化时特别有用，你能保证"title"总在"desc"前面被读取。

3.3 自定义序列化：绕过字段、过滤敏感数据、处理特殊类型

LitJson允许你精细控制每个类型的序列化行为，通过RegisterExporter（导出）和RegisterImporter（导入）注册函数。

场景1：忽略某个字段（如密码）

public class User { public string username; public string password; // 不想存进JSON public int score; } // 注册导出器：当遇到User类型，跳过password字段 JsonMapper.RegisterExporter(typeof(User), (obj, writer) => { User u = (User)obj; writer.WriteObjectStart(); writer.WritePropertyName("username"); writer.Write(u.username); writer.WritePropertyName("score"); writer.Write(u.score); writer.WriteObjectEnd(); });

场景2：将Vector3转为[x,y,z]数组（而非{"x":1,"y":2,"z":3}对象）

JsonMapper.RegisterExporter(typeof(Vector3), (obj, writer) => { Vector3 v = (Vector3)obj; writer.WriteArrayStart(); writer.Write(v.x); writer.Write(v.y); writer.Write(v.z); writer.WriteArrayEnd(); }); JsonMapper.RegisterImporter(typeof(JsonData), typeof(Vector3), (data) => { if (data.IsArray && data.Count == 3) { return new Vector3((float)data[0], (float)data[1], (float)data[2]); } throw new JsonException("Invalid Vector3 array format"); });

场景3：处理DateTime（推荐ISO8601字符串）

JsonMapper.RegisterExporter(typeof(DateTime), (obj, writer) => { DateTime dt = (DateTime)obj; writer.Write(dt.ToString("o")); // "o"格式 = ISO8601完整格式 }); JsonMapper.RegisterImporter(typeof(string), typeof(DateTime), (str) => { return DateTime.ParseExact((string)str, "o", null); });

这些注册必须在首次调用ToJson或ToObject之前完成，通常放在MonoBehaviour.Awake()或静态构造函数里。我习惯建一个JsonConfig.cs：

public static class JsonConfig { static JsonConfig() { // 全局注册 JsonMapper.RegisterExporter(typeof(Vector3), ...); JsonMapper.RegisterExporter(typeof(DateTime), ...); // 密码字段过滤器（针对特定类） JsonMapper.RegisterExporter(typeof(User), ...); } }

这样整个项目统一入口，避免某处忘了注册导致数据错乱。

4. 实操全流程与避坑指南：从编辑器测试到真机部署

4.1 完整工作流：一个可落地的存档系统案例

我们来实现一个真实的玩家存档系统，包含：

• 存档数据结构（含嵌套、字典、数组）；
• 本地文件读写（Application.persistentDataPath）；
• 错误容错（JSON损坏时降级处理）；
• 版本兼容（v1.0字段缺失时提供默认值）。

Step 1：定义存档类（SaveData.cs）

[Serializable] public class SaveData { public int version = 1; // 存档版本号 public string playerName; public int level; public List<Item> inventory; public Dictionary<string, Skill> skills; public Vector3 lastPosition; [System.Serializable] public class Item { public string id; public int count; } [System.Serializable] public class Skill { public int level; public float exp; } }

Step 2：存档管理器（SaveManager.cs）

public class SaveManager : MonoBehaviour { private const string SAVE_FILE = "player.save"; public static void Save(SaveData data) { try { string json = JsonMapper.ToJson(data); string path = Path.Combine(Application.persistentDataPath, SAVE_FILE); File.WriteAllText(path, json); Debug.Log($"Save success: {path}"); } catch (Exception e) { Debug.LogError($"Save failed: {e.Message}"); } } public static SaveData Load() { string path = Path.Combine(Application.persistentDataPath, SAVE_FILE); if (!File.Exists(path)) { Debug.Log("No save file found, returning default"); return CreateDefaultSave(); } try { string json = File.ReadAllText(path); SaveData data = JsonMapper.ToObject<SaveData>(json); // 版本兼容：v1.0无lastPosition字段，设为(0,0,0) if (data.version == 1 && data.lastPosition == default(Vector3)) { data.lastPosition = Vector3.zero; } return data; } catch (JsonException je) { // JSON格式错误，尝试降级：删除损坏文件，返回默认 Debug.LogError($"JSON parse error: {je.Message}. Deleting corrupt save."); File.Delete(path); return CreateDefaultSave(); } catch (Exception e) { Debug.LogError($"Load failed: {e.Message}"); return CreateDefaultSave(); } } private static SaveData CreateDefaultSave() { return new SaveData { version = 1, playerName = "NewPlayer", level = 1, inventory = new List<Item>(), skills = new Dictionary<string, SaveData.Skill>(), lastPosition = Vector3.zero }; } }

Step 3：在游戏里调用

// 保存（如退出游戏时） void OnApplicationQuit() { SaveManager.Save(currentSaveData); } // 加载（如进入主菜单时） void Start() { currentSaveData = SaveManager.Load(); Debug.Log($"Loaded player: {currentSaveData.playerName}, Level: {currentSaveData.level}"); }

这个流程覆盖了90%的Unity存档需求。关键点在于：

• 路径用Application.persistentDataPath：确保Android/iOS/PC路径正确，且不受Unity编辑器重编译影响；
• try-catch分层：JsonException捕获JSON语法错误，通用Exception捕获IO异常；
• 版本字段version：为未来字段扩展留余地，避免旧存档加载失败；
• 降级策略：JSON损坏时删文件而非崩溃，用户体验不中断。

4.2 真机部署必查清单：iOS、Android、WebGL差异点

提示：WebGL下无法用FileAPI，需改写SaveManager：

#if UNITY_WEBGL && !UNITY_EDITOR // WebGL专用：用localStorage private static void SaveToLocalStorage(string key, string value) { using (var www = UnityWebRequest.Put($"http://localhost/{key}", value)) { www.SetRequestHeader("Content-Type", "text/plain"); www.SendWebRequest(); } } #else // 原逻辑 #endif

4.3 高级技巧：流式解析超大JSON、性能优化、内存泄漏预防

技巧1：用JsonReader流式解析10MB+配置文件
当JSON文件超过2MB（如地图数据、技能树），JsonMapper.ToObject会一次性加载全部字符串到内存，易触发GC。改用JsonReader逐块解析：

public static List<EnemyData> ParseEnemiesStream(string filePath) { List<EnemyData> enemies = new List<EnemyData>(); using (FileStream fs = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.Read)) { using (StreamReader sr = new StreamReader(fs, Encoding.UTF8)) { JsonReader reader = new JsonReader(sr); // 跳过根对象开始 reader.ReadToken(); // 读取 { while (reader.Token != JsonToken.EndObject) { string key = reader.ReadToken().ToString(); // 读键名 reader.ReadToken(); // 跳过 : if (key == "enemies") { reader.ReadToken(); // [ while (reader.Token != JsonToken.EndArray) { EnemyData enemy = new EnemyData(); reader.ReadToken(); // { while (reader.Token != JsonToken.EndObject) { string field = reader.ReadToken().ToString(); reader.ReadToken(); // : switch (field) { case "id": enemy.id = reader.ReadToken().ToString(); break; case "hp": enemy.hp = (int)reader.ReadToken(); break; case "type": enemy.type = reader.ReadToken().ToString(); break; } reader.ReadToken(); // 逗号或} } enemies.Add(enemy); reader.ReadToken(); // 逗号或] } } else { reader.Skip(); // 跳过未知字段 } } } } return enemies; }

技巧2：复用JsonWriter减少GC分配
JsonMapper.ToJson(obj)每次调用都新建StringBuilder，高频调用（如每帧存数据）会引发GC。改用复用JsonWriter：

private static readonly StringBuilder sb = new StringBuilder(); private static readonly JsonWriter writer = new JsonWriter(sb); public static string ToJsonFast(object obj) { sb.Clear(); writer.Reset(sb); JsonMapper.Write(obj, writer); return sb.ToString(); }

技巧3：避免JsonData内存泄漏
JsonData内部用ArrayList和Hashtable，未释放会驻留内存。务必在不用时调用Clear()：

JsonData temp = JsonMapper.ToObject(json); // ... 使用temp temp.Clear(); // 释放内部集合 temp = null; // 帮助GC

5. 常见问题速查与独家排错经验

5.1 典型报错与根因分析

5.2 性能对比实测（Unity 2021.3.15f1，Android ARM64）

我们用1000个PlayerData对象（平均JSON长度1.2KB）做序列化耗时测试：

结论：LitJson比JsonUtility慢约2倍，但比Newtonsoft.Json快40%，且内存更可控。对于非高频操作（如存档、配置加载），这200ms差距完全可接受；而它换来的AOT稳定性，是线上事故的“保险丝”。

5.3 五个你绝不会在文档里看到的避坑技巧

1. JsonData的Count陷阱：JsonData数组的Count返回元素个数，但对象的Count返回键值对数量——不是所有键都算数。JsonData obj = new JsonData(); obj["a"] = null;此时obj.Count为0，因为null值被忽略。要判断是否存在键，用obj.Contains("a")，而非obj.Count > 0。

2. 浮点数精度丢失：LitJson默认用double解析数字，"0.1"可能变成0.10000000000000001。若需精确小数（如货币），用字符串存储："price": "19.99"，读取时decimal.Parse(json["price"].ToString())。

3. Android文件路径权限：Application.persistentDataPath在Android 10+需<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />，但Google Play要求targetSdk>=30时禁用。解决方案：改用Application.temporaryCachePath，或用UnityWebRequest上传到服务器。

4. JsonMapper.ToObject<T>的泛型擦除：List<T>在AOT下T类型信息丢失，JsonMapper.ToObject<List<string>>("[]")可能失败。安全写法：JsonMapper.ToObject(typeof(List<string>), "[]") as List<string>。

5. 编辑器与真机差异：Unity编辑器里JsonMapper.ToJson(new object())返回{}，但Android IL2CPP下返回null。永远不要依赖new object()的JSON表现，用具体类代替。

最后分享个小技巧：在JsonMapper.cs里搜索// DEBUG，取消注释几行日志输出，就能看到LitJson内部解析的每一步——哪个字符、什么状态、跳过了什么。这比任何文档都管用，尤其当你面对一个“莫名解析失败”的JSON时，打开DEBUG，3分钟定位到多了一个逗号。技术没有玄学，只有字符和状态。