简介：Newtonsoft.Json 6.0 是一套面向 .NET 平台的 JSON 处理库资源包，包含可直接引用的动态链接库、配套源码和使用文档，用于解决对象与 JSON 数据之间的序列化、反序列化问题，适合在网站接口、微服务通信、配置管理等场景中使用，适合不同阶段的开发者按需参考。压缩包共收录 771 个文件，整体大小 6.29MB，以 477 个 C# 源代码、128 个说明文档、22 个动态链接库、21 个 JSON 样例为核心，同时含有项目工程文件、配置文件、图片和相关授权说明，方便参照和部署。文档与示例覆盖序列化器对比、序列化参数设置、错误处理、日期格式、JSON 与 XML 转换、缩减序列化体积等主题，有助于快速掌握属性控制、性能调优和问题排查等方法，能够帮助深入理解库的实现原理。目前已有 731 人学习浏览，整个资源目录清晰，适合作为开发工具库及学习 Newtonsoft.Json 6.0 的参考资料。
1. 一个老牌JSON库的“钉子户”版本
做.NET开发的朋友，几乎没人没听过Newtonsoft.Json，江湖人称Json.NET。它长期以来就是.NET生态里JSON序列化的事实标准，从.NET Framework 2.0时代一路扛到.NET 8、.NET 9，哪怕微软后来出了官方的System.Text.Json，也没能完全撼动它的地位。而6.0这个版本，更是特殊得不行——它发布于2013到2014年那会儿，算下来已经十年出头，可直到今天，你去翻一些老项目的packages.config或者.csproj，还是能稳稳看到它的身影。
为什么单独聊newtonsoft.json.dll 6.0？因为很多还在维护的老系统、老站点，实际就是把项目死死钉在了Json.NET 6.0上。不是不想升级，是不敢随便升。这里面有“历史遗留”的技术债，有老框架的兼容性限制，也有各种程序集版本冲突挖下的坑。这篇文章，我就围绕这个经典版本，把它是什么、为什么还在用、引用它要注意哪些坑、出问题怎么排查，一次说透。
这篇东西适合谁看？两类人。一类是还在维护老项目的朋友，遇到这个dll报错、找不着北，急需要一份“排雷手册”；另一类是刚接触老代码库的年轻人，面对一个十年前的项目，想知道为什么这个6.0版本的dll地位那么稳，又不清楚它跟新版本之间到底隔着什么。不管你是哪类，这篇文章都能帮你少走弯路。
2. 为什么一堆老项目困在6.0走不出去
很多人不理解，升级一个NuGet包而已，至于吗？在当时的项目环境里，还真至于。Json.NET 6.0是伴随ASP.NET Web API 2.x那批项目流行起来的版本。在VS 2013、VS 2015那个年代，新创建的一个Web API项目，默认引用就是Newtonsoft.Json 6.0.x。而真正把它“锁死”的元凶，其实是微软自家的System.Net.Http.Formatting和System.Web.Http这两个程序集——它们内部强签名引用了Newtonsoft.Json 6.0.0.0这个程序集版本。
什么叫强签名引用？就是调用方程序集的清单里，写死了被调用程序集的公钥令牌、版本号、文化信息。.NET在运行时加载依赖项时，会根据调用方的清单去匹配对应版本。你项目里如果还引用着ASP.NET Web API 2.x那套组件，它们要加载的Newtonsoft.Json版本就是6.0.0.0。这时候你非要升级到Json.NET 7.x或8.x，AssemblyVersion变成了7.0.0.0或8.0.0.0，运行时就懵了——找半天找不到6.0.0.0，直接给你抛一个FileLoadException: 未能加载文件或程序集“Newtonsoft.Json, Version=6.0.0.0”。
组件之间版本不对付，这是老项目里最让人头大的事。升级Json.NET本身不算难，难得是项目里可能有一堆第三方库都跟这个dll有依赖关系，你升了一个，牵出八个问题。所以现实就是，很多系统能不动就不动，让Newtonsoft.Json.dll 6.0一直陪跑到今天。反正它能满足需求，序列化快，功能全，稳定，那就继续用着呗。
不过，6.0版本和其他更老的4.x、5.x版本之间，还夹着一个重要的行为变化，这也是一部分项目固守6.0的重要原因——6.0把默认的日期格式从微软的\/Date(1376058000000)\/格式切换成了ISO 8601格式（形如2013-08-09T19:40:00+08:00）。如果你接手过2013年前后的老系统，会发现有些接口到现在还在返回\/Date(...)\/这种老式日期串，那就是因为项目用的还是Json.NET 5.x甚至更早。6.0这个版本，算是新旧行为转换的一个分水岭，理解这一点，你在排查序列化日期格式问题时，心里就有谱了。
3. 不会还有人不知道这个dll怎么配吧
3.1 通过NuGet获取6.0版本
尽管6.0已经是很老的版本，NuGet上依然可以正常下载。在Visual Studio的“解决方案资源管理器”里右键项目，选择“管理NuGet程序包”，然后在“浏览”页签里输入Newtonsoft.Json，这时候默认搜到的是最新版，比如13.x。想安装6.0，需要手动点一下“版本”下拉框，拉到最底下，选中6.0.8，再点安装就行。
我的习惯是用程序包管理器控制台操作，更方便，也方便写文档记录。直接在“工具”菜单里打开“NuGet包管理器”下的“包管理器控制台”，然后敲下面这行命令：
Install-Package Newtonsoft.Json -Version 6.0.8系统会自动把Newtonsoft.Json.dll放进项目的bin目录。6.0.8是6.0这条线里的最后一个修复版本，我强烈建议没用过6.0的朋友，如果需要选6.0版本，就选6.0.8，别去用6.0.1之类更早的小版本。原因很简单，6.0.8修复了已知的不少bug，性能也有一定优化，而且它和6.0.0在程序集版本上是一致的（都是6.0.0.0），不会因为小版本升级引发额外的版本冲突。
3.2 这个版本里有哪些关键的dll目录
从NuGet下载下来的包里，其实不只有一个dll，而是按目标框架分了好几个目录。你到packages\Newtonsoft.Json.6.0.8\lib下面会看到net20、net35、net40、net45这些子文件夹。每个文件夹里的dll几乎一样，但编译目标不同，对应不同版本的.NET Framework。
net20对应.NET Framework 2.0，程序集版本也是6.0.0.0net35对应.NET Framework 3.5，支持LINQ to JSONnet40对应.NET Framework 4.0net45对应.NET Framework 4.5及以上
NuGet在安装包的时候，会根据你项目的目标框架自动选择引用哪个目录下的dll，正常情况下你不需要手动去管。但也有人喜欢“纯手工引用”，直接右键引用浏览dll文件，这时候就得注意别选错目录。比如你的项目目标是.NET Framework 4.0，但你手滑引用了net45目录下的dll，编译时不会立刻报错，运行到某些API时却可能出现奇怪的问题，因为net45版本的代码里可能用到了一些4.5才有的新API。说白了，你在VS里看不到明显的错误提示，但运行时环境撑不住。
这里我提醒一点：如果你的项目目标框架是.NET Framework 4.5以上，NuGet默认会把6.0.8的net45版本引进来。如果你是在老项目里手动替换dll，尽量先确认项目的目标框架，再去对应的目录里拿文件，不要拿错了。
3.3 6.0.8的依赖要求
Json.NET 6.0.8这个版本对依赖是极其克制的。它不像现在很多包，东拉西扯装一堆间接依赖。它唯一的依赖是Microsoft.CSharp（针对C#的dynamic关键字支持），而且只在net35以上的版本里才有这个依赖。对于用传统C#类型写法和JObject、JArray这类API的人来说，基本可以当作“零依赖”。
换句话说，只要你的项目跑在完整的.NET Framework上，把dll扔进去就能跑。这也是为什么它那么适合做“手工引用”——不用考虑一堆传递依赖的破事。
4. 用Newtonsoft.Json 6.0做序列化的关键细节
4.1 最常用的几个API
Json.NET 6.0的API跟现在的新版本差别并不大，核心类还是那几个。最常用的就是JsonConvert.SerializeObject和JsonConvert.DeserializeObject，这对儿方法堪称万能钥匙。一个是把对象变成JSON字符串，一个是把JSON字符串还原成对象。
比如一个最简单的例子：
var product = new Product { Id = 1, Name = "测试商品", Price = 99.99m }; string json = JsonConvert.SerializeObject(product); Console.WriteLine(json); // 输出: {"Id":1,"Name":"测试商品","Price":99.99}反过来，从JSON字符串变成对象也就一行：
string json = "{\"Id\":1,\"Name\":\"测试商品\",\"Price\":99.99}"; var product = JsonConvert.DeserializeObject<Product>(json);但是，实际项目里我们经常需要处理更复杂的场景，比如字段名和C#属性名不一致、需要忽略某些字段、处理循环引用等。这时候就需要用到JsonSerializerSettings和JsonProperty特性了。
4.2 JsonProperty特性和命名策略
老项目里最容易遇到的一个需求是命名映射。前端传过来的JSON字段是下划线风格product_name，而后端C#属性是帕斯卡命名ProductName。这时候在属性上挂一个JsonProperty特性就行：
public class Product { [JsonProperty("product_id")] public int Id { get; set; } [JsonProperty("product_name")] public string Name { get; set; } }注意了，6.0版本对特性的支持已经很完善了，这一点跟新版本一样。所以在老项目里通过特性控制序列化行为，完全没毛病。但对于更高级的全局命名策略，比如CamelCasePropertyNamesContractResolver，6.0也是支持的，只是用法上稍微绕一点，需要实例化一个ContractResolver再扔进Settings里。
另外一个很实用的场景是忽略空值和默认值。比如某个字段没值就不输出到JSON里，可以这样配置：
var settings = new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore }; string json = JsonConvert.SerializeObject(obj, settings);NullValueHandling在老项目里超级常用，因为数据库里取出来的很多字段都是null，序列化出去一堆"field":null不但看着脏，数据量也大。6.0的这套设置和新版本完全一致，没踩过坑的话照着这个写就行。
4.3 用JObject处理动态JSON
有一种场景是，我们事先不知道JSON的结构，或者不想为每种结构都定义一个C#类。比如对接第三方接口，对方返回一段嵌套很深的JSON，我只想取其中一层。这时候用JObject就很爽。
string json = "{\"code\":200,\"data\":{\"list\":[{\"id\":1,\"name\":\"a\"},{\"id\":2,\"name\":\"b\"}]}}"; JObject obj = JObject.Parse(json); var list = obj["data"]["list"]; foreach (JToken item in list) { Console.WriteLine(item["name"]); }JObject、JArray、JToken这套JSON.NET的“LINQ to JSON”体系，在6.0版本里已经相当成熟了。不过要是你的项目里大量使用这种动态解析方式，升级新版本时要注意一个问题：某些API返回的类型在新版本里从JToken变成了JValue之类更具体的类型，可能造成细微的兼容性差异。这一点虽然不是大问题，但在老项目升级时很容易被忽略。
4.4 循环引用处理
对象循环引用是许多序列化库的痛点。比如一个订单对象里有客户对象，客户对象里又有订单列表，直接序列化会无限递归，最终抛异常。Json.NET 6.0对循环引用的处理有两种方案。
第一种是序列化时设置ReferenceLoopHandling.Ignore，遇到循环引用就自动忽略那个属性：
var settings = new JsonSerializerSettings { ReferenceLoopHandling = ReferenceLoopHandling.Ignore };第二种是保留引用信息，序列化出来的结果带$id和$ref这些元数据，反序列化时可以完整还原对象图。不过在6.0这个版本里，第二种方式有时候会坑到人——如果你在反序列化时没有配套开启PreserveReferencesHandling，很可能多出一堆不想要的$id字段。我的经验是：除非你要序列化一个复杂的对象图并且必须完整还原，否则别开保留引用，直接用Ignore处理循环引用，逻辑简单，输出干净。
5. 版本冲突和运行时错误的排查实录
5.1 最经典的“未能加载文件或程序集”
做老项目维护，遇到最多的就是这句：
System.IO.FileLoadException: 未能加载文件或程序集“Newtonsoft.Json, Version=6.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed”或它的某一个依赖项。找到的程序集清单定义与程序集引用不匹配。
这个错误的直接原因有两个。第一种，项目里实际引用的dll版本不是6.0.0.0，但某个组件在编译时想要的是6.0.0.0。比如你手动把dll换成了10.0.0.0，但System.Web.Http还是按6.0.0.0去找，就崩了。第二种，你引用的确实是6.0.0.0，但运行时加载到的版本跟配置里绑定重定向的版本不一致。
先说最简单的处理方式：给应用加bindingRedirect配置。在web.config（网站项目）或app.config（桌面应用）的<configuration>节点下，加这样一段：
<runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" /> </dependentAssembly> </assemblyBinding> </runtime>这段配置的意思是：凡是程序集版本在0.0.0.0到6.0.0.0之间的，统统重定向到6.0.0.0。这样即使某个库编译时按5.0版本或者6.0版本去引用，运行时也都统一加载6.0.0.0这一个，避免出现多版本并存互相打架。
但这里要特别注意，如果项目里有另一个库要求的是更高版本（比如8.0.0.0），你把所有版本都重定向到6.0.0.0是行不通的，运行时会报“无法加载更高版本”的错。所以，绑定重定向的本质是“统一”，而不是“降级”。用之前一定要把整个项目的依赖关系梳理清楚。
5.2 用Fuslogvw追踪程序集加载
如果加了bindingRedirect还是报错，就该请出大杀器——程序集绑定日志查看器（Fuslogvw.exe）。这个工具在Visual Studio的开发人员命令行里可以启动，也可以直接到C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools之类的目录下去找。
打开Fuslogvw，点“设置”，把“日志位置”改成“磁盘”，绑定失败那栏选上“全部”。然后重新运行程序触发报错，再回到Fuslogvw点“刷新”，就能看到一条条加载失败的记录。点开某一项，日志里会详细记录“尝试加载哪个程序集”“从哪里加载”“为什么失败”。
我在排查上面那个FileLoadException时，就是用这个工具发现是某个第三方组件引用了Newtonsoft.Json, Version=4.5.0.0，而我的bindingRedirect只写了oldVersion="0.0.0.0-6.0.0.0"，没有把4.5.0.0包进去，导致那个组件找不到对应的程序集。改成oldVersion="0.0.0.0-6.0.0.0"之后，问题就消失了。
5.3 同一个项目里同时存在多个版本的dll
还有一种更隐蔽的情况：项目里同时引用了Json.NET的不同版本。比如主项目引用了6.0.8，但某个子项目或第三方类库又单独带了一份13.0.0的dll，而且它们的“复制本地”都没关掉。编译时VS会警告CS1704（“已多次定义具有相同名称的程序集”），运行时则完全看运气——加载到哪一份全看程序集探测顺序，因此经常出现“开发环境正常，部署到服务器就报错”的诡异问题。
排查思路很简单。先在bin目录下搜索所有Newtonsoft.Json.dll文件，看是不是有多份。如果有，再确定到底应该保留哪一份。如果是因为老项目的框架限制只能使用6.0版本，那就把项目里所有对Json.NET的引用统一改成6.0.8，针对那些实在没法改的第三方库，那就写bindingRedirect强制重定向。如果项目只用到了基础的序列化和反序列化功能，代码层面几乎不用改。
实在遇到那种“两个组件都强依赖不同版本且没法统一”的死局，还有最后一招：使用extern alias给不同版本取别名。这个属于比较高级的用法，要在项目属性里为两个dll分别设置别名，代码里用extern alias JsonV6;和extern alias JsonV13;来区分。我在实际项目里只遇到过一次必须用这种方案的场景，能用bindingRedirect解决的，尽量别折腾这条路。
6. 老项目里躲不开的几个坑
6.1 日期格式变化引发的联动效应
Json.NET 6.0把默认日期序列化格式换成了ISO 8601，这个我在前面提到过。但这里要补充一个容易踩的细节：如果你的项目里同时使用了ASP.NET Web API，而且没有显式配置JsonSerializerSettings，Web API里面的格式化器可能仍然按老式日期格式输出。
原因在于，ASP.NET Web API的JsonMediaTypeFormatter内部有自己的一套默认设置，它不一定跟JsonConvert.DefaultSettings完全同步。很多时候你需要手动在WebApiConfig.cs里设置一下：
config.Formatters.JsonFormatter.SerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;如果不做这个设置，就会出现“同一个系统里，有的接口返回ISO日期，有的接口返回老式\/Date(...)\/”的分裂情况。前端做适配的时候就特别痛苦，每个接口都判断一次日期格式。
6.2 目标框架是.NET 3.5的老项目特别注意
如果你维护的项目还跑在.NET Framework 3.5上，那真的要格外小心。Json.NET 6.0虽然支持net35，但一些高级API依赖的某些基类库在3.5下是不存在的。最典型的是System.Runtime.Serialization里的一些类型，以及C#的dynamic关键字在部分场景下的支持问题。
我的建议是，.NET 3.5项目里尽量少用dynamic和ExpandoObject来操作JSON，老老实实定义POCO类，用强类型反序列化，稳定性高很多。另外，6.0是为.NET 3.5编译的版本和（不是为4.0编译的），如果你手抖引用了net40目录下的dll，运行时各种怪异问题会层出不穷。
6.3 用ILSpy反编译确认版本差异
排查老项目里“为什么这段代码新版本能跑，旧版本跑不了”的问题时，只靠官方文档往往不够。Json.NET各个版本之间的行为差异太多，官方文档又主要维护最新版，老版本的具体实现细节基本要靠自己去看代码。这时候我习惯直接上ILSpy，把两个版本的dll都反编译开，对比关键方法的具体实现。
比如我曾经处理过一个诡异问题：同样的代码在Json.NET 6.0里序列化一个DataTable，输出结果里的Decimal值会带引号变成字符串，而新版本输出的是数字。挂上ILSpy一对比才发现，6.0版本对Decimal类型的转换逻辑里，先做了一次Convert.ToString，导致结果变成了字符串。这种细节，不反编译看代码，光靠试错能试到怀疑人生。
7. 最后的实际心得
手头有老项目需要继续跟Newtonsoft.Json.dll 6.0打交道的话，几个建议直接给你。不要在当前业务代码里同时混用多个版本的Json.NET API，所有序列化操作尽量走统一封装的一个工具类，以后真要升级换新，改一个文件就完事了。另外，每次部署前把bin目录下的Newtonsoft.Json.dll的文件版本记下来，跟正式环境的对比一下，能省去很多“本地好的、线上挂了”的排查时间。
讲真，Json.NET 6.0这个版本放到今天看，性能和功能确实比不上13.x那些新版本，比如缺少JsonSerializerOptions、对Span<T>的支持为零。可它毕竟是撑起过一代.NET Web应用的老功臣，稳定得让人觉得无聊，而“无聊”恰恰是生产环境最宝贵的品质。如果你只是维护旧系统，就让它继续安静地待着吧，别手痒升级。真正要考虑升级的时候，一定是新功能带来的收益远大于迁移成本，而不是单纯因为“版本太老看着难受”。
最后再留一个排查的锦囊：遇到Json.NET相关的疑难杂症，英文搜索时直接带AssemblyVersion和你项目的目标框架版本，往往能找到StackOverflow上同病相怜的老哥留下的答案。中文社区里关于这个老版本的内容更少，很多坑还是得靠自己踩。
本文还有配套的精品资源，点击获取
