1. 问题引入：一个看似简单的“Unexpected character”背后

在.NET生态里做开发，尤其是处理前后端数据交互或者配置文件解析，Newtonsoft.Json（现在也叫Json.NET）几乎是绕不开的一个库。它功能强大、灵活，社区支持度也高，但正是这种灵活性，有时也会带来一些意想不到的“惊喜”。今天要聊的这个JsonReaderException，特别是伴随Unexpected character错误信息的，就是其中一个典型的、容易让人挠头的场景。

你可能正在愉快地写着代码，调用一句JsonConvert.DeserializeObject<T>(jsonString)，满心期待一个漂亮的对象实例化出来，结果却迎面撞上一个异常，告诉你遇到了一个“意外的字符”。这时候，你的第一反应很可能是：“我的JSON字符串看起来没问题啊？” 然后开始逐字符检查，甚至怀疑是不是编码问题。这个错误信息本身太笼统了，它只告诉你“这里不对”，但没告诉你“为什么不对”以及“怎么才对”。

我最近就在一个数据迁移项目中踩了这个坑。从旧系统导出的数据，经过一些处理后用JSON格式暂存，在新系统里反序列化时频繁报错。错误信息千篇一律是Unexpected character，但发生的位置和字符却各不相同。这个过程促使我系统地梳理了一遍Newtonsoft.Json在解析时遇到“意外字符”的各种成因和解决方案。这不仅仅是解决一个异常，更是理解JSON解析器如何“思考”的过程。

2. 核心原理：JsonReader如何“阅读”你的字符串

要解决问题，得先明白问题是怎么产生的。Newtonsoft.Json的反序列化过程，底层依赖于一个JsonReader（通常是JsonTextReader）来遍历输入的JSON文本。这个阅读器就像一个严格的语法分析器，按照 JSON规范（RFC 8259） 逐字符地解析输入流。

当JsonReader在某个位置期待一个特定的语法元素（比如期待一个属性名的开始引号，或者一个值的开始），而下一个字符不符合它的预期时，它就会抛出JsonReaderException，并在Message中指明是哪个字符导致了问题，以及这个字符在文本流中的大概位置（行、列）。这就是Unexpected character的由来。

关键在于“期待”二字。阅读器的状态机处于不同状态时，它对下一个字符的合法集合有不同的定义。例如：

• 在解析完一个属性名和冒号后，阅读器处于“等待属性值”状态。此时，合法的起始字符可能是：{（对象开始）、[（数组开始）、"（字符串开始）、t/f/n（true/false/null的开始）、数字或-。
• 在解析完一个数组元素后，阅读器处于“等待数组分隔符或结束”状态。此时，合法的下一个字符只能是,（下一个元素）或]（数组结束）。

任何不符合当前状态预期的字符，都会被判定为“Unexpected”。这个机制本身是健壮的，它保证了JSON的语法正确性。问题往往出在：我们提供给阅读器的文本，与我们（以及阅读器）所认为的“文本”不一致。

3. 高频诱因排查：从数据源头到解析配置

遇到Unexpected character，不要急着去改反序列化的代码，而应该遵循一个从外到内、从数据到配置的排查路径。以下是几个最常见的原因和对应的诊断、解决方法。

3.1 数据源污染：不可见字符与编码问题

这是最隐蔽也最常见的一类问题。你的JSON字符串在日志里、在文本编辑器里“看起来”完全正确，但实际上可能掺杂了肉眼不可见的字符。

1. BOM（字节顺序标记）UTF-8编码的文件或网络流开头有时会包含一个BOM（EF BB BF）。对于纯JSON文本而言，BOM不是一个合法的JSON令牌起始字符。当JsonReader第一个读到的字符是BOM时，它会直接报告Unexpected character。

如何诊断与解决：

// 诊断：检查字符串的第一个字符 string jsonString = GetJsonFromSomewhere(); if (!string.IsNullOrEmpty(jsonString) && jsonString[0] == '\uFEFF') // UTF-8 BOM 字符 { Console.WriteLine("字符串包含BOM头。"); } // 解决：移除BOM jsonString = jsonString.TrimStart('\uFEFF'); // 或者，在读取文件/流时指定不识别BOM // using (var reader = new StreamReader(filePath, new UTF8Encoding(false))) // false 表示不检测BOM // { // jsonString = reader.ReadToEnd(); // }

2. 零宽字符、控制字符等数据可能来自剪贴板、富文本编辑器、或者经过不规范处理的字符串，里面可能包含\u200b（零宽空格）、\u0000（空字符）等。这些字符在大部分文本显示环境中不可见，但会破坏JSON结构。

如何诊断与解决：

// 诊断：输出字符串的字符代码 for (int i = 0; i < jsonString.Length; i++) { if (char.IsControl(jsonString[i]) && jsonString[i] != '\n' && jsonString[i] != '\r' && jsonString[i] != '\t') { Console.WriteLine($"位置 {i} 发现控制字符: {(int)jsonString[i]:X4}"); } } // 解决：在确保不影响真实数据的前提下，可以过滤掉非常规空白字符 // 注意：此方法可能误伤合法字符串内的转义字符，需谨慎评估。 var cleanedJson = new string(jsonString.Where(c => !char.IsControl(c) || c == '\n' || c == '\r' || c == '\t').ToArray());

3. 编码不一致服务器返回的是UTF-8，但客户端用ASCII或GBK去解码，会导致中文字符等变成乱码，这些乱码字符很可能无法被JSON解析器识别。确保在整个数据流转链路上（数据库、API、文件读写）使用统一的编码，推荐始终使用UTF-8。

3.2 JSON文本格式错误：语法与结构

这是最直接的原因，即字符串本身就不是一个有效的JSON。

1. 缺失或多余的逗号、引号、括号这是新手和老手都容易犯的错误。例如，在JSON对象或数组的最后一个元素后面多了一个逗号（虽然一些JavaScript引擎允许，但严格的JSON规范不允许）。

// 错误示例：尾部多余逗号 { "name": "John", "age": 30, }

// 错误示例：属性名未用双引号包围（单引号不符合JSON规范） { 'name': 'John', "age": 30 }

如何诊断与解决：

• 使用在线JSON校验工具：如 JSONLint ，将你的JSON字符串粘贴进去，它能精确定位语法错误。
• 使用Newtonsoft.Json自带的校验：在尝试反序列化前，可以先尝试用JToken.Parse()或JObject.Parse()，它们的错误信息有时更直观。

  try { var token = JToken.Parse(jsonString); // 如果解析成功，说明语法基本正确 } catch (JsonReaderException ex) { Console.WriteLine($"JSON语法错误: {ex.Message}"); Console.WriteLine($"错误路径: {ex.Path}"); Console.WriteLine($"行{ex.LineNumber}, 列{ex.LinePosition}"); // 根据ex.LineNumber和ex.LinePosition定位源码错误位置 }

2. 字符串内的未转义字符JSON字符串中，双引号"、反斜杠\、换行符等必须被转义。如果你拼接JSON字符串时，直接拼接了包含这些字符的变量，就会出错。

// 错误示例 string userName = "User\"Name"; // 包含双引号 string badJson = $"{{\"name\": \"{userName}\"}}"; // 拼接后JSON为 {"name": "User"Name"}，引号未转义

如何解决：永远不要手动拼接JSON字符串！使用JsonConvert.SerializeObject来生成JSON。

var obj = new { name = userName }; string goodJson = JsonConvert.SerializeObject(obj); // 库会自动处理转义

3.3 反序列化目标类型与JSON结构不匹配

JsonReader在解析时是“类型驱动”的。当你调用DeserializeObject<T>时，阅读器会结合目标类型T的结构来指导解析。如果不匹配，就会在深层嵌套的某个地方触发Unexpected character。

1. 属性类型不匹配JSON中某个属性的值是字符串"123"，但你的C#模型里对应的属性是int。解析器在读到开头的引号"时，期待的是数字，于是报错。

2. 结构不匹配JSON是一个对象{}，但你尝试反序列化到一个List<T>；或者JSON是数组[]，你却反序列化到一个简单对象。

如何诊断与解决：

• 检查异常中的Path属性：JsonReaderException的Path属性会告诉你解析进行到哪个属性时出错了，这是定位问题的关键。

  catch (JsonReaderException ex) { Console.WriteLine($"错误发生在路径: {ex.Path}"); // 例如：`items[0].price` }

• 使用弱类型模型先行解析：如果不确定JSON结构，可以先反序列化到JObject或dynamic，检查其实际结构。

  dynamic dynamicObj = JsonConvert.DeserializeObject(jsonString); Console.WriteLine(dynamicObj.someProperty?.GetType()); // 查看实际类型

• 调整C#模型：使模型属性类型与JSON数据类型兼容。对于可能多变的字段，可以使用object类型，或者使用JsonConverter进行自定义转换。

3.4 配置与上下文：DateParseHandling与FloatParseHandling

JsonSerializerSettings里的一些全局配置，会改变JsonReader对原始文本的解读方式，如果配置与数据不匹配，也会导致“意外字符”。

1. DateParseHandling默认情况下，Newtonsoft.Json会将符合ISO 8601格式的字符串（如"2023-10-27T12:00:00Z"）自动识别为DateTime。但如果你将DateParseHandling设置为DateParseHandling.None，阅读器就不会进行这种识别，它会将整个字符串当作一个普通的JSON字符串值来解析。这通常没问题。然而，如果数据中包含了不符合日期格式的字符串，但阅读器却试图去解析它，就可能在中途失败。更常见的问题是，当你不希望日期被自动转换时，这个默认行为反而会造成困扰。

2. FloatParseHandling这个设置处理浮点数解析。默认是FloatParseHandling.Double。如果你的JSON中包含一个特别大或特别小的数字（例如科学计数法1e-300），而你的模型是decimal类型，解析器在尝试将读取到的double转换为decimal时可能会溢出。但更直接导致Unexpected character的情况是，如果数字的格式本身有问题（比如包含逗号1,234.56，而你的区域设置不是这样），在解析数字的初始阶段就会报错。

如何诊断与解决：明确你的数据格式，并显式设置JsonSerializerSettings。

var settings = new JsonSerializerSettings { DateParseHandling = DateParseHandling.None, // 明确不自动解析日期字符串 FloatParseHandling = FloatParseHandling.Decimal, // 明确使用Decimal解析所有浮点数（注意溢出风险） // 还可以设置文化信息，确保数字格式一致 Culture = CultureInfo.InvariantCulture }; var result = JsonConvert.DeserializeObject<MyModel>(jsonString, settings);

4. 实战：一个综合排查案例

假设我们有一个从老旧API获取的JSON字符串，反序列化时抛出异常：Unexpected character encountered while parsing value: *. Path ‘items[0].code’, line 3, position 25.

第一步：定位与截取根据错误信息，我们知道问题出在items数组第一个元素的code属性上，在第3行第25列附近。我们先把有问题的JSON片段提取出来。

{ "items": [ { "id": 1, "code": "ABC*123", // 假设*是问题字符 "name": "Item 1" } ] }

第二步：肉眼与工具校验肉眼观察“ABC*123”，*在字符串内部，看起来是合法的。用JSONLint校验，语法也通过。这说明问题不是简单的语法错误。

第三步：深入分析“期待”状态阅读器在解析到code属性的值“ABC*123”时，它处于“正在解析字符串值”的状态。在这个状态下，它读取字符直到遇到结束的双引号”。在字符串内部，绝大多数字符都是允许的，除了未转义的双引号”和反斜杠\。那么*显然是允许的。为什么还会报错？

第四步：考虑编码与不可见字符我们检查*字符前后的原始字节。有可能这个*根本就不是真正的星号（ASCII 42）。例如，它可能是从Windows-1252等编码错误转换而来的其他字符，只是显示为*。我们输出字符的Unicode码点：

string problemCode = “ABC*123”; foreach (char c in problemCode) { Console.WriteLine($”{c}: {(int)c}”); } // 如果输出不是 42，那就找到了问题。

第五步：考虑反序列化目标类型检查我们的C#模型：

public class Item { public int Id { get; set; } public SomeEnum Code { get; set; } // 啊哈！Code被定义成了枚举类型！ public string Name { get; set; } }

问题根源找到了！JsonReader在解析完属性名“code”和冒号后，看到了一个字符串的开始引号”。它知道目标类型是SomeEnum，所以它期待读取到一个枚举的字符串表示或数字值。但是，在它尝试将整个字符串“ABC*123”匹配为枚举值时，它发现这个字符串根本不在枚举的定义中。然而，错误报告有时不会直接说“无法转换”，而是在解析的早期，当它试图协调字符串解析和枚举匹配的逻辑时，就抛出了Unexpected character。这里的*可能只是被错误信息当作“第一个不匹配的点”报告了出来。

解决方案：

1. 修改数据源：确保API返回的code值是有效的枚举名称或数值。
2. 修改模型：将Code属性类型改为string，然后在业务逻辑中处理枚举转换。
3. 使用自定义JsonConverter：为SomeEnum类型编写一个转换器，更灵活地处理像“ABC*123”这样的字符串，例如将其映射到一个默认的枚举值或进行日志记录。

5. 高级场景与自定义处理

当上述常规方法都无效，或者你需要处理非常规的JSON数据时，就需要更高级的手段。

5.1 使用自定义的JsonReader你可以继承JsonTextReader并重写相关方法，在字符级别进行预处理。例如，过滤掉特定的控制字符，或者在解析数字前进行格式清洗。

public class SanitizingJsonReader : JsonTextReader { public SanitizingJsonReader(TextReader reader) : base(reader) { } public override bool Read() { // 在父类Read之前，可以预览下一个字符 // 这里是一个简化示例，实际逻辑更复杂 bool success = base.Read(); // 可以根据TokenType和Value进行一些清理 return success; } } // 使用方式 using (var sr = new StringReader(jsonString)) using (var reader = new SanitizingJsonReader(sr)) { var serializer = new JsonSerializer(); var obj = serializer.Deserialize<MyModel>(reader); }

注意：重写JsonReader需要深入理解其状态机，复杂度较高，通常作为最后的手段。

5.2 预处理JSON字符串在反序列化之前，对字符串进行全局的、基于正则表达式或简单字符串操作的清理。这种方法简单粗暴，但需要注意不要破坏合法的JSON结构，尤其是字符串内部的字符。

// 示例：移除所有ASCII控制字符（除了制表、换行、回车） string sanitizedJson = Regex.Replace(jsonString, @”[\p{C}-[\t\n\r]]”, string.Empty);

警告：此方法风险极高，可能误删字符串值内合法的转义字符（如\n,\t）。仅在你完全了解数据格式且无更好办法时使用。

5.3 实现错误恢复机制有时，你并不想因为一个字段的错误而放弃整个文档的解析。可以配置JsonSerializer来忽略错误，但这需要谨慎处理。

var settings = new JsonSerializerSettings { Error = (sender, args) => { // args.ErrorContext.Error 包含原始异常 // args.ErrorContext.Path 包含错误路径 Console.WriteLine($”忽略错误在 {args.ErrorContext.Path}: {args.ErrorContext.Error.Message}”); args.ErrorContext.Handled = true; // 标记错误已处理，解析继续 } }; var result = JsonConvert.DeserializeObject<MyModel>(jsonString, settings); // 结果中，出错字段会保持默认值（如null, 0）

6. 调试工具与最佳实践

工欲善其事，必先利其器。掌握好的工具和习惯能极大提升排查效率。

6.1 内置诊断工具

• JsonReaderException属性：充分利用Message,Path,LineNumber,LinePosition。Path是最有用的信息。
• JsonTextReader的LineNumber和LinePosition：虽然异常里提供了，但在自定义读取逻辑时可以直接访问。

6.2 可视化与校验工具

• JSON格式化与高亮：使用IDE插件（如VS的JSON Viewer）或在线工具，让结构一目了然，容易发现括号、逗号不匹配。
• JSON Schema验证：如果API有定义Schema，使用Schema验证工具可以在数据层面提前发现问题，而不仅仅是语法问题。

6.3 防御性编程与最佳实践

1. 始终验证输入：在反序列化外部数据（API响应、文件、用户输入）前，如果可能，先进行校验。
2. 使用Try-Catch进行优雅降级：反序列化代码一定要放在try-catch块中，并具体捕获JsonReaderException和JsonSerializationException，给用户或日志提供有意义的错误信息，而不是让程序崩溃。
3. 记录原始数据：在捕获异常时，将出错的原始JSON字符串（或片段）记录到日志中。这对于复现和调试线上问题至关重要。
4. 保持模型与契约的同步：当API的JSON结构发生变化时，及时更新C#数据模型（DTO）。可以考虑使用契约测试（如Pact）来保证双方的一致性。
5. 考虑使用System.Text.Json：对于新项目，可以评估使用.NET Core 3.0+引入的System.Text.Json。它性能更好，默认更严格（例如默认不自动转换日期），有时更严格的规定反而能提前暴露数据问题。当然，它的灵活性和生态目前还不如Newtonsoft.Json。

处理Newtonsoft.Json的Unexpected character错误，本质上是一场与数据质量和解析器期望之间的对话。最关键的步骤不是盲目尝试，而是系统性地缩小排查范围：从异常信息定位到具体路径，检查该处的原始数据（包括不可见字符），对比数据与模型的类型契约，最后考虑解析器的配置上下文。养成使用校验工具、记录原始数据、编写防御性代码的习惯，能让你在面对这类问题时更加从容。