一个服务读取本地 JSON 配置,测试环境一切正常,到了另一台机器上,中文全变成了问号,时间字段还莫名其妙少了八小时。配置本身没改,代码也没改,问题出在文件的编码和日期的时区信息上。这类问题不会抛异常,只会让数据「看起来不对」,排查时很容易怀疑到别的地方去。

文件和序列化看起来是 API 调用,实际上每个参数都在和操作系统、字符集、时区打交道。路径怎么拼、文件用什么编码、JSON 字段名怎么映射、日期带不带时区,这些决定一旦选错,后面每读一次文件、每传一次数据都会重复出错。

这篇按「路径、读写、编码、JSON、时间」的顺序讲。示例都在本机 .NET 8 控制台项目里跑过,命令和输出照实贴出,临时文件写在系统临时目录,不碰项目目录。

先看那个路径和编码一起出问题的例子

先做一个最小实验,看看 Path.Combine 在两个参数都像完整路径时会怎么处理,以及文件实际写到哪里、占多少字节:

using System;
using System.IO;
using System.Text;

Console.WriteLine(Path.Combine(@"C:\data", @"C:\logs\a.txt"));
Console.WriteLine(Path.Combine(@"C:\data", "logs", "a.txt"));

var dir = Path.Combine(Path.GetTempPath(), "csdemo-file");
Directory.CreateDirectory(dir);
var file = Path.Combine(dir, "note.txt");
File.WriteAllText(file, "中文内容", new UTF8Encoding(false));
Console.WriteLine($"exists={File.Exists(file)} bytes={new FileInfo(file).Length}");

本机输出:

dotnet run
C:\logs\a.txt
C:\data\logs\a.txt
exists=True bytes=12

第一个输出值得注意:第二个参数是带盘符的完整路径时,Path.Combine 直接返回它,前一个参数被丢掉了。这不是 bug,而是它的设计规则:只要后一个片段是根路径,组合结果就以它为准。很多人用它拼「基础目录加用户传入的文件名」,结果用户传了一个绝对路径,文件就写到了别的地方。

第二个输出是正常拼接。这里能看出 Path.Combine 只负责用分隔符把片段连起来,它不会检查文件是否存在,也不会阻止 .. 这样的上级目录片段。四个汉字写入后文件是 12 字节,说明 UTF-8 下每个汉字占 3 字节,并且我们传入的编码不带 BOM。

如果把同样的内容用 GBK 写一遍,文件会小一些,因为 GBK 下这两个汉字各占 2 字节。但文件大小不是判断编码的可靠依据,短文本尤其容易误判。真要确认,还是看字节序列或者问清楚数据来源。

路径拼接与路径穿越

路径处理的第一条原则是:不要用字符串加法拼路径。手写 base + "\\" + name 在 Windows 上看似没问题,换到 Linux 就全错,而且多一个斜杠、少一个斜杠都可能出问题。用 Path.Combine 让框架处理分隔符,是最低要求。

第二条原则是:用户输入不能直接当路径片段。假设一个下载接口接收文件名,代码写成 Path.Combine(root, fileName),用户传入 ..\..\windows\system32\config,组合出来的路径就跑到根目录外面去了。这叫路径穿越,属于安全问题,不是「路径拼错」这么简单。

只检查字符串里有没有 .. 并不可靠,编码、大小写、不同平台的分隔符都能绕过。正确做法是把用户输入拼进固定根目录后,调用 Path.GetFullPath 得到绝对路径,再检查它是否真的以根目录的绝对路径开头。对不上就拒绝,不要尝试「修正」。

具体写法可以是这样:先取根目录的完整路径,拼上用户输入,再取完整路径,最后做前缀比较。比较时要注意末尾的分隔符,避免 C:\data2 被误判为在 C:\data 下面。如果目标平台可能是 Linux,还要考虑大小写和路径分隔符的差异。

除了 Combine,Path 类还有几个常用方法值得记住:GetFileName 取最后一段文件名,GetDirectoryName 取所在目录,GetExtension 取扩展名,ChangeExtension 替换扩展名,GetTempPath 拿系统临时目录。这些方法只做字符串和路径规则层面的处理,不会真的访问磁盘。需要判断文件是否存在,用 File.Exists;需要创建目录,用 Directory.CreateDirectory,它会在父目录不存在时一并创建。

另一个细节是路径长度。Windows 传统上有 260 字符左右的限制,虽然现代 .NET 和系统设置放宽了不少,但深层目录加长文件名仍然可能出问题。生成路径时留一点余量,不要把用户输入原样嵌进去还指望它永远短。

读文件:File 快捷方法和 FileStream 各管什么

小文件用 File.ReadAllText、File.ReadAllBytes 最省事,一行就能读完。它们的代价是一次性把整个文件装进内存:读一个 200MB 的日志文件,进程内存就至少多 200MB,再加上字符串解码的临时对象,峰值可能更高。文件越大,这个做法越危险。

大文件要用 FileStream 配合缓冲读取,边读边处理。下面是一个按行读取的骨架:

using var fs = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
using var reader = new StreamReader(fs, Encoding.UTF8);
string? line;
while ((line = reader.ReadLine()) != null)
{
    // 处理一行
}

FileStream 的参数分别管:打开模式(新建、打开、追加、截断)、访问权限(只读、只写、读写)、共享方式(别的进程能不能同时打开)。共享方式选错,会出现「文件被另一个进程占用」的异常,尤其是在两个程序同时读写同一个日志或配置时。

写入时同样有快捷方法和流两种。小配置用 File.WriteAllText 够了;持续写日志、导出大文件,要用 FileStream 或 StreamWriter,并考虑追加模式。追加模式不会清空原文件,适合日志;覆盖模式会先截断,适合整体重写配置。

流对象一定要释放,最稳的写法是 using 声明或 using 块。FileStream 不释放,文件句柄会一直占着,Windows 上表现为「文件被占用」,Linux 上表现为文件描述符慢慢耗尽。即使读取过程中抛异常,using 也能保证关闭。不要依赖垃圾回收来关文件,回收时间不确定,线上跑久了迟早出问题。

还有一个跨平台的常识:Linux 上文件名区分大小写,Windows 默认不区分。代码里写死 config.json,在 Windows 上打开 Config.json 也能成功,换到 Linux 就找不到。路径里的每一段都按实际文件名写,不要靠大小写碰运气。文件系统怎么组织目录、怎么分配空间,可以看 文件系统那一篇,这里只关心 C# 这一层怎么调用。

编码:乱码不是「文件坏了」

乱码的本质是「写的时候用一种编码,读的时候用了另一种」。一个文件里存的是字节,字节本身没有意义,只有按正确的字符集解码,才能变成你看到的文字。UTF-8 下「中」是三个字节,GBK 下是两个字节,用错编码读出来就是一堆问号或方块。

现代 .NET 的 File.ReadAllText 默认使用 UTF-8,这比旧框架的默认行为清楚很多。但「默认 UTF-8」不代表所有文件都是 UTF-8。别人用记事本另存为 GBK,或者旧系统导出的 CSV 是 GB18030,直接读就会乱码。遇到乱码先确认源文件的真实编码,再显式传入对应的 Encoding。

UTF-8 无 BOM

跨平台最通用的选择。中文正常显示,字节数比 GBK 多一些。Web、JSON、配置文件优先用它,写入时明确不写 BOM。

UTF-8 带 BOM

文件开头多三个字节,某些旧工具靠它识别编码。但它会污染文件内容:读进字符串后开头可能带一个看不见的字符,解析 JSON 或 CSV 时容易出错。

BOM 是字节顺序标记,本质上是文件开头用来声明编码的几个字节。UTF-8 的 BOM 是 EF BB BF。很多解析器能容忍它,但也有一些严格要求「第一个字符就是 {」的解析器会直接报错。写配置文件、JSON、CSV 时,默认不要带 BOM;如果对方系统明确要求,再单独处理。

File.WriteAllText(path, text, new UTF8Encoding(false));   // 不写 BOM
File.WriteAllText(path, text, new UTF8Encoding(true));    // 写 BOM

读取时如果怀疑有 BOM,可以检查字节数组开头是不是 EF BB BF,或者用 StreamReader 让它自动处理。但不要在所有读取路径上都假设有 BOM,那会让正常文件多出奇怪的分支。

需要读 GBK 或 GB18030 时,注意 .NET 默认只带一部分常见编码,访问这些代码页可能需要先注册 CodePagesEncodingProvider,否则 Encoding.GetEncoding("GBK") 会抛异常。注册是进程级的一次性操作,放在程序入口做一次即可,不要每次读文件都注册。

System.Text.Json:字段名、中文和忽略规则

.NET 自带的 JSON 库是 System.Text.Json,不引第三方包就能用。它默认按属性名原样输出,C# 属性习惯用 PascalCase,前端习惯用 camelCase,两边对不上就需要配置命名策略。

using System;
using System.Text.Json;

class Order
{
    public int Id { get; set; }
    public decimal Total { get; set; }
    public DateTime CreatedAt { get; set; }
    public string Note { get; set; } = "";
}

class Program
{
    static void Main()
    {
        var order = new Order {
            Id = 1, Total = 12.5m,
            CreatedAt = new DateTime(2026, 11, 7, 10, 30, 0, DateTimeKind.Unspecified),
            Note = "加急"
        };
        var json = JsonSerializer.Serialize(order, new JsonSerializerOptions {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        });
        Console.WriteLine(json);
    }
}

本机输出:

{
  "id": 1,
  "total": 12.5,
  "createdAt": "2026-11-07T10:30:00",
  "note": "\u52A0\u6025"
}

属性名变成了 camelCase,符合前端习惯。但中文被转义成了 \u52A0\u6025。这不是错误,JSON 规范允许这种写法,解析后仍然是「加急」。如果希望输出可读的中文,可以设置 Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,但要清楚这会放宽转义规则,输出到 HTML 等场景时要另外做安全处理。

反序列化时,命名策略要两边一致。序列化用了 camelCase,反序列化也要设置同样的策略,否则属性对不上,字段全是默认值,而且不会报错。这是最常见的「JSON 解析成功但数据为空」的原因。更稳妥的做法是用 [JsonPropertyName("id")] 显式标注每个属性的名字,不依赖全局策略。

还有几个默认行为要知道:没有对应属性的 JSON 字段会被忽略;C# 属性没有 setter 时默认不会被反序列化赋值;null 和「字段缺失」在默认配置下可能得到相同结果。需要严格校验时,可以开启「未知字段报错」或者用可空类型区分「没传」和「传了 null」。

JsonSerializerOptions 对象最好复用,不要每次序列化都 new 一个。它内部会缓存类型元数据,反复创建新实例会让缓存失效,序列化频繁时性能明显下降。把常用的 Options 定义成静态只读字段,全项目共用一份,既省事也省开销。

DateTime 的 Kind:八小时差从哪来

上面的输出里,日期是 2026-11-07T10:30:00,没有时区后缀。因为创建时用的是 DateTimeKind.Unspecified,序列化器不知道这是哪个时区的时间,就按原样输出。反序列化回来,Kind 仍然是 Unspecified。

// 接上面代码,json 是序列化后的字符串
var parsed = JsonSerializer.Deserialize<Order>(json, new JsonSerializerOptions {
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
})!;
Console.WriteLine($"kind={parsed.CreatedAt.Kind} note={parsed.Note}");

本机输出:

kind=Unspecified note=加急

问题在于,DateTime 本身不保存时区偏移,它只有一个 Kind 标记:UTC、Local 或 Unspecified。跨机器传输时,如果一边按本地时间理解,另一边按 UTC 理解,就会出现几个小时的偏差。中国时区是 UTC+8,看上去正好差八小时。

解决办法不是「统一用 DateTime 然后祈祷」,而是明确传输格式。跨时区传输优先用 DateTimeOffset,它带偏移量,序列化后形如 2026-11-07T10:30:00+08:00,接收方不会误解。如果必须用 DateTime,就在系统内部统一存 UTC,展示时再按用户时区转换,并且在序列化格式里明确带 Z 后缀。

如果已经拿到一个 Unspecified 的 DateTime,想把它当成本地时间转成 UTC,可以调用 DateTime.SpecifyKind 先明确 Kind,再调用 ToUniversalTime。反过来,从 UTC 转本地用 ToLocalTime。这两个方法依赖运行机器的时区设置,同一份代码在不同机器上结果可能不同。跨时区服务最好显式使用 TimeZoneInfo,不要依赖默认本地时区。

只在同一台机器、同一个时区里用的时间,用 DateTime 问题不大。只要数据会跨机器、跨时区、跨服务传输,就应该考虑 DateTimeOffset 或统一 UTC。数据库里存什么、接口返回什么、界面显示什么,这三层最好在项目开始时就定好,不要等到线上对不上账再改。

真实项目里的现象与排查方向

现象真实原因第一步查什么
中文全部变成问号或方块写入和读取用了不同编码确认源文件编码,读取时显式传入对应的 Encoding
JSON 解析报「第一个字符不是有效值」文件开头带 BOM,解析器把 BOM 当成内容用字节查看开头是否为 EF BB BF,写入时用无 BOM 的 UTF-8
文件写到了意料之外的目录用户传入绝对路径,Path.Combine 丢弃了前面的基础目录打印最终完整路径,检查是否以允许的根目录开头
下载接口能读到系统文件文件名含 ..,路径穿越没有被拦住用 GetFullPath 后做前缀校验,不要只过滤字符串
大文件读取时进程内存暴涨用了 ReadAllText 或 ReadAllBytes 一次性加载改成 FileStream 加缓冲,边读边处理
JSON 反序列化后属性全是默认值命名策略不一致,字段名对不上检查序列化和反序列化的 Options 是否相同,或改用显式标注
日期差八小时DateTime 的 Kind 丢失,双方对本地时间和 UTC 的理解不同看序列化字符串有没有时区后缀,确认是否该用 DateTimeOffset
提示文件被另一个进程占用FileStream 的共享模式不允许同时读写检查 FileShare 参数,确认是否有另一个进程还开着文件

这张表里的问题有一个共同点:程序往往不会在出错的地方报错,而是在下游某处表现出「数据不对」。所以排查时先确认数据的来源和格式,再去看使用数据的代码,顺序不要反。

边界与代价

文件 API 和序列化库都有各自的限制,提前知道能少踩很多坑:

  • ReadAllText 只适合小文件:文件大小接近可用内存时,一次性读取会让进程濒临崩溃。日志、导出文件、上传文件都应该流式处理。
  • 文件写入不是原子操作:直接覆盖配置文件时,如果进程在写到一半时崩溃,文件可能只剩半截。需要原子替换时,先写临时文件,再重命名覆盖。
  • 编码不能靠猜:默认 UTF-8 能覆盖大多数现代文件,但旧系统导出的 GBK、带 BOM 的 UTF-8 都需要显式处理。猜错不会有异常,只会得到坏数据。
  • System.Text.Json 不是万能解析器:它对格式要求比较严格,注释、尾随逗号默认不支持。要读取宽松格式,需要显式配置,或者换用更宽松的解析方式。
  • DateTime 不带时区:它只适合「本地日历上的时间」。跨时区传输用 DateTimeOffset,或者统一用 UTC 加明确的格式约定。
  • 路径安全要按平台考虑:Windows 的分隔符、大小写规则和 Linux 不同。写跨平台代码时,路径一律用框架 API 处理,不要手拼。

还有一个容易被忽略的成本:频繁打开关闭小文件很慢。每次 File.ReadAllText 都是一次系统调用加磁盘访问,在循环里读几百个小文件,耗时可能远超你的预期。能合并读取的就合并,能缓存的就缓存,但缓存要处理好失效,别读到过期配置。

当天能自己验证的练习

以下练习都在一个控制台项目里完成,改 Program.cs 后执行 dotnet run:

  1. 分别用 Path.Combine(@"C:\data", @"C:\logs\a.txt") 和两个普通片段拼接,打印结果,确认绝对路径会覆盖前一个参数。
  2. 把同一个中文字符串用 UTF8Encoding(false) 和 UTF8Encoding(true) 各写一次,用字节查看器对比文件开头,确认 BOM 的三个字节是否存在。
  3. 用 GBK 编码写一个中文文件,再用默认 UTF-8 读回来,记录乱码的样子;然后显式用 GBK 读,确认恢复正常。
  4. 序列化一个带中文和日期的对象,分别用默认配置和 UnsafeRelaxedJsonEscaping 输出,比较中文是否被转义;再把反序列化的命名策略去掉,观察属性是否变成默认值。
  5. 用 DateTimeKind.Utc 和 DateTimeKind.Unspecified 各创建一个时间,序列化后比较字符串后缀,确认时区信息有没有被写进去。

小结

三句话收一下:路径用 Path.Combine 拼,用户输入必须做完整路径校验;小文件可以用 File 快捷方法,大文件用 FileStream 流式处理;编码和时区都要显式约定,UTF-8 无 BOM 加 DateTimeOffset 是跨平台项目比较稳的默认组合。

数据能可靠地存到磁盘之后,下一步是让它通过网络出去。下一篇讲 HttpClient 和 Socket:为什么不能每次请求都 new 一个 HttpClient、超时应该设在哪、响应为什么必须释放,以及同步等待异步结果为什么会把线程卡死。