C#如何写入JSON文件？常见问题与排错指南

在C#开发中，将数据持久化存储为JSON格式文件是很多项目的基础需求，无论是配置信息保存还是业务数据导出都会用到这个功能。实现这个功能可以借助.NET内置的System.Text.Json库，也可以选择第三方流行的Newtonsoft.Json库，两种方式各有适用场景。

一、C#写入JSON文件的两种实现方式

1. 使用System.Text.Json写入

System.Text.Json是.NET Core 3.0之后内置的JSON处理库，不需要额外安装依赖，适合轻量级的JSON操作场景。首先需要定义要序列化的实体类：

using System.Text.Json;

// 定义测试用的实体类
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public DateTime CreateTime { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        // 创建测试数据
        User user = new User
        {
            Id = 1,
            Name = "张三",
            Age = 25,
            CreateTime = DateTime.Now
        };

        // 配置序列化选项，设置缩进格式，支持中文编码
        JsonSerializerOptions options = new JsonSerializerOptions
        {
            WriteIndented = true,
            Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
        };

        // 序列化对象为JSON字符串
        string jsonStr = JsonSerializer.Serialize(user, options);
        // 写入文件，指定编码为UTF-8避免乱码
        File.WriteAllText("user.json", jsonStr, System.Text.Encoding.UTF8);
        Console.WriteLine("System.Text.Json写入完成");
    }
}

2. 使用Newtonsoft.Json写入

Newtonsoft.Json（也叫Json.NET）是老牌的JSON处理库，兼容性更好，支持更多自定义序列化规则，需要先通过NuGet安装Newtonsoft.Json包。实现示例如下：

using Newtonsoft.Json;
using System.IO;

// 同样使用上面的User实体类
class Program
{
    static void Main(string[] args)
    {
        User user = new User
        {
            Id = 2,
            Name = "李四",
            Age = 28,
            CreateTime = DateTime.Now
        };

        // 序列化对象，设置缩进格式
        string jsonStr = JsonConvert.SerializeObject(user, Formatting.Indented);
        // 写入文件，默认编码为UTF-8，也可手动指定
        File.WriteAllText("user_newton.json", jsonStr);
        Console.WriteLine("Newtonsoft.Json写入完成");
    }
}

二、常见问题与排错方法

1. 写入的JSON文件中文出现乱码

这是最常见的问题，主要原因是写入文件时没有指定正确的编码，或者序列化时转义了中文字符。排错步骤如下：

• 如果使用System.Text.Json，检查JsonSerializerOptions的Encoder是否设置为JavaScriptEncoder.UnsafeRelaxedJsonEscaping，同时File.WriteAllText要指定编码为Encoding.UTF8
• 如果使用Newtonsoft.Json，默认情况下不会转义中文，若出现乱码检查文件写入的编码是否为UTF-8，避免用默认的ANSI编码写入
• 用记事本打开生成的JSON文件，查看另存为时的编码选项，确认是否为UTF-8，若不是则调整写入编码

2. 提示文件路径不存在或没有写入权限

这类问题通常是路径配置错误或者权限不足导致的，排查方法：

• 如果使用相对路径，确认程序运行目录是否存在对应文件夹，比如要写入data/user.json，需要先判断data文件夹是否存在，不存在则创建：Directory.CreateDirectory("data")
• 如果使用绝对路径，检查路径是否拼写正确，比如盘符是否存在，路径中的文件夹是否真实存在
• 如果是写入系统目录（如C盘根目录、Program Files目录），需要以管理员权限运行程序，或者更换为有权限的目录，比如用户的文档目录

3. 序列化失败，提示找不到合适的构造函数或者属性无法序列化

这种情况通常是实体类的定义不符合序列化要求导致的，排查方向：

• 检查实体类是否有公共的无参构造函数，System.Text.Json默认要求实体类有公共无参构造函数，若没有可以手动添加，或者配置JsonSerializerOptions的IncludeFields属性
• 检查要序列化的属性是否为公共的get和set访问器，私有属性默认不会被序列化，如果需要序列化私有属性，需要自定义序列化转换器
• 如果实体类包含循环引用（比如A类包含B类属性，B类又包含A类属性），需要配置序列化选项忽略循环引用，System.Text.Json可以设置ReferenceHandler = ReferenceHandler.IgnoreCycles，Newtonsoft.Json可以设置ReferenceLoopHandling = ReferenceLoopHandling.Ignore

4. 写入的JSON格式不符合预期，缺少字段或者字段名不对

这类问题通常是序列化配置导致的，常见排查点：

• 如果需要自定义字段名，比如JSON中字段名为user_name，而实体类属性是UserName，可以使用特性标注：System.Text.Json用[JsonPropertyName("user_name")]，Newtonsoft.Json用[JsonProperty("user_name")]
• 如果有部分字段不需要序列化，可以用忽略特性：System.Text.Json用[JsonIgnore]，Newtonsoft.Json用[JsonIgnore]
• 检查是否配置了自定义的契约解析器或者转换器，导致字段被过滤或者重命名

三、总结

C#写入JSON文件的核心逻辑就是先将对象序列化为JSON字符串，再将字符串写入文件，两种主流库的实现方式都很简单。开发过程中遇到问题可以先对照上述常见场景排查，大部分问题都是编码、路径、序列化配置这几类原因导致的，掌握基础排查方法就能快速定位并解决问题。

C#JSON写入Newtonsoft_JsonSystem_Text_Json文件操作修改时间：2026-06-10 05:24:14