打开Unity 2022的包管理器，我闭着眼都能写完那行com.unity.nuget.newtonsoft-json，但身边还是有同事每次新建项目都要为装Newtonsoft.Json折腾半小时。因为这东西说简单是真简单，可一旦卡住——要么是找不到包名、要么是装了没反应、要么是报错说俩程序集冲突——网上答案又老又散，照抄还经常翻车。这篇就把安装到验证再到日常使用的路径一次捋清楚，顺便把我踩过的几个典型坑也放进去。
1. 为什么Unity 2022还得“额外装”JSON库：JsonUtility的边界问题
1.1 JsonUtility能干什么，干不了什么
很多新人在知乎上问“Unity自带的JsonUtility是不是就够了”。我的回答一直是：看项目，但大多数做网络通信、配置表、存档系统的项目，光靠JsonUtility根本不够。它最大的问题是功能裁剪得太厉害。
JsonUtility有三个硬伤：第一，不支持Dictionary<K,V>，序列化字典的时候直接静默返回{}，连报错都不带；第二，不支持多态，你声明一个基类字段，往里塞子类对象，序列化输出时子类的字段全丢；第三，不支持带参数的构造函数、不能直接用JsonProperty这种Attribute做字段名映射，枚举处理也老出幺蛾子。另外还有私有字段、只读属性这些限制，写在官方文档里但没几个人认真看。
有人会说，那用JsonUtility.FromJson配合Serializable类做存档不是挺香吗？没错，这种场景它确实香——性能好、零依赖、API 两个函数搞定。问题在于现在游戏项目里的数据交换早就不是“一个类对一段完整JSON”那么简单了，后端接口返回的可能是个动态结构，可能带嵌套数组，可能字段名是驼峰而C#成员是帕斯卡，你再用JsonUtility写兼容层，那代码就是一场灾难。
1.2 Newtonsoft.Json的生态位置
在C#的JSON处理生态里，Newtonsoft.Json差不多是“事实标准”级别的存在。不管是ASP.NET Core（早期版本）、桌面端工具链，还是第三方Unity插件，几乎都默认依赖它。Unity官方也不硬扛了，直接把Newtonsoft.Json打包成了官方包：com.unity.nuget.newtonsoft-json。这名字前面带com.unity，意味着你不需要去GitHub拉源码、不需要下载DLL扔Plugins、不需要在工程里维护第三方文件，官方已经在维护这条依赖链和Unity生命周期里的兼容性。
同类的替代品不是没有：LitJSON、MiniJSON、还有微软的System.Text.Json。但LitJSON功能弱，System.Text.Json在Unity里的支持又不够完善，尤其泛型反序列化和AOT平台上有历史坑。所以Newtonsoft依然是折衷下来最省心的选择。它的功能边界大得多：支持动态类型、匿名对象、字典、多态、自定义JsonConverter、[JsonProperty]字段映射，这些才是我在项目里真正高频使用的能力。
1.3 动手前先确认你的Unity版本
安装前先看一眼Help > About Unity，确定你在哪个版本区间。Unity 2022这个系列里，2022.1、2022.2、2022.3 LTS我都用过，Package Manager界面细节略有差异，但“Add package by name”这个功能块在2021以后就已经稳定存在了，2022系列肯定都有。如果项目还在用2019、2020的老版本，UI位置会不同，而且解析出来的默认包版本也可能不一样——比如2019/2020里默认解析到的可能是2.0.0，2022里能直接解析到3.2.1。老版本也不是不能用，只是你在照着本文操作前，得先评估一下自己的Unity版本支不支持“按包名添加”，不支持的话就得走manifest.json手动改或者下载源码包，那就绕远了。所以我的建议很直接：新项目就用2022.3 LTS起步，省得在工具版本上反复折腾。
2. 最省事的安装路线：Package Manager按包名直装
2.1 官方包名com.unity.nuget.newtonsoft-json的来龙去脉
先把这个包名拆开理解，后面出问题你才知道去哪找原因。com.unity说明是Unity官方账号在维护发布，nuget.newtonsoft-json指的是它源自NuGet上同名的.NET标准包。这个包的本质就是一个封装壳，核心DLL还是Newtonsoft.Json，只是Unity把它做成了符合UPM规范的官方包。正因为是官方包，所以它能直接和Unity的包解析机制、版本依赖、Editor生命周期整合，能做到“一键安装”“自动更新”“依赖管理”。
这个包在旧版本号上容易让人迷惑。Unity官方已经迭代过好几轮：早期版本从1.x到2.0.0，2.0.0主要对应.NET Standard 2.0和Unity 2020时代的兼容；等到Unity 2021.3和2022.x时代，3.x版本成了主流。3.x最大的变化是底层Newtonsoft.Json版本升级到13.x，支持了更多现代C#特性和序列化场景。如果你是从老文章里抄了一个2.0.0版本号，在2022里也不是不能用，只是没必要。
2.2 Package Manager窗口的三步操作
安装流程我现在背得滚瓜烂熟。打开Unity工程后，按顺序走：
- 顶部菜单栏点
Window > Package Manager，打开包管理器窗口。 - 窗口左上角有下拉列表，一般默认是
My Packages。但你搜索官方包时用My Packages反而找不到，因为它还没有被安装进当前工程。你需要把左上角下拉切换成Unity Registry或My Registries，具体名称在不同版本里略有出入。在2022.3里是Unity Registry。 - 列表加载后，直接点窗口左上角的“+”号按钮，会弹出三个选项：
Add package by name...、Add package by git URL...、Add package by tarball...。选第一项Add package by name...。 - 在弹出的输入框里填包名
com.unity.nuget.newtonsoft-json，下面会自动带出一个版本号输入区域。你可以不填版本号直接点Add，让Unity解析出默认匹配版本；也可以像我一样手动指定。 - 点击Add后，Unity会开始从注册表下载包，状态栏显示加载进度，等回到包管理器列表且包名字前出现绿色对勾，就说明安装成功。
整个过程不需要重启Unity，不需要改任何代码，也不用手动去Assets目录找东西。这也是为什么我一直推荐新项目优先走Package Manager而不是下载DLL：包管理器里能看到的依赖，团队协作用manifest.json锁版本锁得清清楚楚，出问题也好排查。
2.3 追求完全可控？直接改manifest.json
不过图形界面有个小毛病——它在团队协作场景下不够“显式”。Unity的包依赖全部记录在Packages/manifest.json里，人一多，每个成员手动点Add，版本可能不一样，最后合代码合出一堆“我机器上能跑你机器上报错”的诡异问题。所以我更建议团队项目改由直接编辑manifest.json来管理。
用代码编辑器打开Packages/manifest.json，在dependencies对象里加一行：
{ "dependencies": { "com.unity.nuget.newtonsoft-json": "3.2.1", "com.unity.collab-proxy": "2.2.0" } }保存后切回Unity窗口，编辑器会自动检测到manifest变化，然后在后台执行包解析。解析完就能在包管理器里看到这个包。如果你想锁死全团队都用同一个版本，这种方式最稳；后续升级也只需要改版本号再保存，Unity会自己完成版本切换。注意改完如果Editor卡住不刷新，Ctrl+R重新编译一下脚本，或者干脆重启一下编辑器，这属于Unity的老毛病，跟这个包本身无关。
3. 装完别急着写业务：版本确认与快速自测
3.1 如何确认包真的加载成功
别以为点了Add就高枕无忧。有几次我明明看到包管理器里出现了Newtonsoft.Json，结果编译还是报“Newtonsoft.Json不存在”。后来发现是因为工程里存在Assembly Definition（asmdef）文件，导致脚本被分到了自定义程序集，而自定义程序集默认不会自动引用Newtonsoft.Json。编译报错就是CS0246，把using Newtonsoft.Json标红。
所以装完之后我现在的流程是：先不写业务代码，只写一个最简验证脚本跑通序列化-反序列化闭环，确保引用和环境没问题，再动手集成到具体模块里。验证脚本不需要复杂，放工程里任意位置先跑一下编辑器测试即可。
3.2 一段最小验证脚本，跑通序列化闭环
新建一个C#脚本，起名NewtonsoftSmokeTest.cs，放到Assets/Editor目录下也行，直接放Assets根目录也没问题。脚本内容：
using UnityEngine; using Newtonsoft.Json; public class NewtonsoftSmokeTest { [System.Serializable] public class PlayerData { public string playerName; public int level; public float hp; public System.Collections.Generic.Dictionary<string, int> items; } [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)] static void Run() { var data = new PlayerData { playerName = "测试玩家", level = 42, hp = 99.5f, items = new System.Collections.Generic.Dictionary<string, int> { ["sword"] = 1, ["potion"] = 3 } }; string json = JsonConvert.SerializeObject(data); Debug.Log("序列化结果: " + json); var parsed = JsonConvert.DeserializeObject<PlayerData>(json); Debug.Log($"反序列化: 玩家={parsed.playerName}, 等级={parsed.level}, 物品药水数量={parsed.items["potion"]}"); } }把这个脚本挂到场景里的任意对象上，进入PlayMode后看Console输出。如果能看到序列化后的JSON字符串包含items字典里的键值对，且反序列化取出的items["potion"]等于3，说明Newtonsoft.Json已经完全正常工作了。
为什么要特意验证字典？因为JsonUtility做不到这件事，这正是选择Newtonsoft的核心价值。这个最小用例测通了，后面的业务代码才有信心。
3.3 命名空间“不存在”的几种真实根因
编译报CS0246: The type or namespace name 'Newtonsoft' could not be found的时候，先别急着怀疑安装出错。按以下顺序排查：
- 打开Package Manager，确认包确实在已安装列表里。如果在
Unity Registry里能看到它但状态不是已安装，说明刚才点Add根本没成功，重新Add一次。 - 检查脚本所在程序集。如果脚本文件夹下有asmdef文件，打开看看
Assembly Definition References列表里有没有引用Unity.Nuget.Newtonsoft.Json或类似名称。UPM包装配出来的程序集名通常可以从包文档里查到，但最简单粗暴的办法是删掉这个asmdef、把脚本挪到无asmdef的文件夹里，再编一次。能编过说明就是asmdef引用缺失。 - 检查是不是开了
Player Settings > Configuration > Api Compatibility Level里的.NET Standard 2.1选项，某些包在纯.NET Standard配置文件下表现不同，但这极少会导致命名空间直接消失。真有这种情况，切回.NET Framework试试。 - 最后再看一眼Packages目录下的
manifest.json里有没有这行依赖，如果被之前的版本管理器误删了，手动补回来。
这套排查流程我写进过团队文档，基本上任何“装了不能用”的问题五分钟内能定位完。
4. 不只会装，还要会用：从JSON文件到对象映射的实战写法
4.1 用JsonProperty优雅解决字段名映射
实际项目里，C#类成员名通常按帕斯卡命名法，而后端接口返回的JSON字段名大多是驼峰或蛇形。如果两者不一致，最笨的办法是写一堆中间层代码去拼接，而Newtonsoft只需要在字段上挂[JsonProperty]属性。
using Newtonsoft.Json; public class ServerResponse { [JsonProperty("status_code")] public int StatusCode { get; set; } [JsonProperty("server_time")] public long ServerTime { get; set; } [JsonProperty("data")] public ResponseData Data { get; set; } }这样反序列化时"status_code"就会自动映射到StatusCode属性上，反之序列化时会输出"status_code"而不是"StatusCode"。这个功能配合JsonSerializerSettings里的NullValueHandling、Formatting.Indented等选项，基本可以覆盖绝大多数接口对接需求。我接触过的团队里很多人在用[Serializable]加JsonUtility，遇到字段名不匹配就再包一层DTO，绕了一大圈，其实一个Attribute就能解决。
4.2 和UnityWebRequest配合做网络JSON解析
Unity里做网络请求最常用的就是UnityWebRequest，但很多新人会把DownloadHandler.text拿回来后硬拼字符串，然后再用JsonConvert.DeserializeObject转对象。这个流程本身没问题，但有一些细节值得注意：UnityWebRequest的下载结果默认使用UTF-8解析，如果服务端响应头里没标字符集，中文可能乱码；另外在WebGL平台上，UnityWebRequest的SendWebRequest协程模式和字典反序列化的组合要特别注意平台差异。下面是一个我常用的封装片段：
using System.Collections; using UnityEngine; using UnityEngine.Networking; using Newtonsoft.Json; public class ExampleApiClient : MonoBehaviour { public IEnumerator FetchPlayerData(string url, System.Action<PlayerData> onSuccess, System.Action<string> onError) { using (UnityWebRequest req = UnityWebRequest.Get(url)) { req.timeout = 10; yield return req.SendWebRequest(); if (req.result != UnityWebRequest.Result.Success) { onError?.Invoke(req.error); yield break; } try { string raw = req.downloadHandler.text; PlayerData data = JsonConvert.DeserializeObject<PlayerData>(raw); onSuccess?.Invoke(data); } catch (JsonException ex) { Debug.LogError($"JSON解析失败: {ex.Message}"); onError?.Invoke(ex.Message); } } } }注意我在解析外层包了try/catch (JsonException)。这样服务端一旦返回了非正常结构（比如网关错误页面的HTML文本），不会把整个协程杀死，而是能回调错误信息到业务层。这个习惯救过我很多次，尤其是在国内SDK对接时，各种网关中间件返回的“错误页面”根本不是JSON，不捕获直接崩。
4.3 字典、枚举、日期：三个高频处理点逐一说明
我整理一下在用Newtonsoft时遇到的三个比较典型的细节，新手最容易在这儿踩坑。
第一个是字典的键类型。Dictionary<int, T>在JSON序列化时键会被转成字符串，这是JSON标准规定的，Newtonsoft会自动处理这个转换，但你反序列化时如果键类型不是string，得注意格式严格性。比如Dictionary<long, int>里，JSON里的键如果写成了1.0，反序列化就会报错。老老实实全用字符串键最安全。
第二个是枚举的处理。Newtonsoft默认会把枚举序列化成数字，这在可读性上还行，但后端如果期望的是枚举名字符串，你需要在枚举字段上加[JsonConverter(typeof(StringEnumConverter))]，或者在JsonSerializerSettings里全局注册。我习惯在全局settings里统一注册，省得每个枚举都加Attribute：
var settings = new JsonSerializerSettings { Converters = new List<JsonConverter> { new StringEnumConverter() }, NullValueHandling = NullValueHandling.Ignore, Formatting = Formatting.None }; string json = JsonConvert.SerializeObject(obj, settings);第三个是时间日期。Unity原生的JsonUtility对DateTime基本无能为力，而Newtonsoft默认ISO 8601格式，解析起来非常省心。但要注意时区问题：如果服务端返回带时区偏移的字符串（如2024-06-01T12:00:00+08:00），Newtonsoft会转成本地时间存储；如果不带时区，它默认按本地时间解析。建议团队里约定一种统一格式，否则跨时区项目会出现“接口数据对不上”的诡异问题。
5. 安装使用中的几个隐藏坑与性能建议
5.1 与第三方插件内置Newtonsoft DLL的冲突
这是最容易让人崩溃的坑，没有之一。
很多老牌第三方插件（比如某些语音SDK、广告SDK、数据分析SDK）为了省事，直接在Assets/Plugins目录下塞了一份Newtonsoft.Json.dll。当你的项目又通过Package Manager安装了同一份Newtonsoft.Json后，就会在一部分平台上看到编译错误或运行时行为错乱：类型存在于两个程序集中，Editor环境里有时没事，真机构建时直接爆炸。
解决办法有两条路。第一条：找到插件目录下的Newtonsoft.Json.dll，把它从构建流程里排除，后缀名改成.dll.bak或在Plugin Importer里取消勾选所有平台。第二条：如果插件对DLL路径有硬编码依赖，那就只能把Package Manager里的包退掉，继续用插件自带DLL，但这样你就失去了官方包的版本管理优势。我的原则是，尽量清扫插件目录里的重复DLL，保留官方包版本统一管理。
排查时怎么快速找到是谁塞的DLL？在Unity编辑器里打开Assets目录，点右上角搜索框，输入Newtonsoft.Json.dll，所有文件会列出来。看清楚路径，基本就能判断是哪个插件带进来的了。
5.2 IL2CPP / Android 平台上的AOT编译问题
Unity的iOS和Android平台构建默认使用IL2CPP，IL2CPP对反射的使用限制很多。Newtonsoft.Json是一个重度依赖反射的库，虽然新版通过内置的“IL2CPP代码裁剪”兼容层解决了不少问题，但你在使用高级特性时仍然可能翻车。
最常见的异常是ExecutionEngineException: Attempting to call method 'X' for which no ahead of time (AOT) code was generated。出现这个异常，一般是你用了类似DeserializeObject<T>，但T是一个只在运行时才出现的类型，IL2CPP没能在编译期生成对应的泛型代码。解决办法有两个：一是确保这个类型在某个地方有显式引用，比如写个TypeSnippet类把所有泛型实例化一遍；二是在Assets/link.xml里保留相关类型，防止代码裁剪把它们剥掉了。
<linker> <assembly fullname="Newtonsoft.Json"> <type fullname="Newtonsoft.Json.JsonConvert" preserve="all" /> </assembly> </linker>说实话，这个坑不是所有人都能踩到，但一旦踩到，网上能查到的有效信息特别散。你要是做多平台发布，尤其是iOS包，建议提前在Build Settings里切到IL2CPP跑一次PlayMode测试，别等提审前才暴露。
5.3 性能不是遮羞布：什么时候继续用JsonUtility
最后聊一个很多人容易走极端的话题。
我在团队里确实见过有人把项目里所有JSON解析全部换成Newtonsoft之后，性能监控曲线很难看，然后又回头把一部分代码改回JsonUtility。这里面的权衡我觉得应该是这样的：
- 如果你只是序列化一个简单的、结构固定的存档类，字段不多、没有字典、没有嵌套多态，那JsonUtility足够快且零依赖，没必要引入Newtonsoft。
- 如果JSON来自不可控的外部接口，结构复杂、字段命名不规范、可能需要动态扩展，那Newtonsoft仍然是更稳的选择。
- 如果对性能极端敏感，比如每帧都要处理大量的JSON数据，建议两个都测一下。从我的经验看，JsonUtility在简单类上比Newtonsoft快三到五倍，但项目里真正卡性能的地方很少是纯JSON解析，往往是网络层、数据库、纹理资源那块。
我自己现在的习惯是“默认Newtonsoft，简单存档或性能热点用JsonUtility”，两者可以共存。因为它们虽然都叫“Json”，但目标场景不重叠，不存在二选一的非此即彼。
说到底，安装只是第一步，真正重要的是知道手里的工具适合解决什么问题。我在把Newtonsoft.Json引入团队项目之后，最大的感受不是“多了个库”，而是终于不用再被JsonUtility的字典和多态限制反复折磨了。装包本身只要一分钟，真正的成本是你是否愿意在项目里为不同JSON场景设计合适的解析策略——这个思路捋顺了，后面写数据层、配置表、协议对接都会轻松很多。
：原理、Python实现与参数调优)
