运营上传了一个 CSV,导入工具报错:第一列 id 不存在。打开文件看,第一行明明写着 id,name,amount,一个字都没错。把文件下载下来用十六进制查看器打开,才发现开头多了三个字节 EF BB BF,这是 UTF-8 的 BOM。程序把 BOM 当成第一个字符的一部分,列名实际变成了「BOM 加 id」,当然对不上。

文件相关的问题大多这样:代码逻辑没错,错在文件本身和你以为的不一样。编码、换行、BOM、路径分隔符、文件锁,每一项都能让程序在别人的机器上表现完全不同。这一篇讲 Java 的 NIO 文件 API:路径怎么表示、字符集怎么指定、大文件怎么流式读、目录怎么遍历,以及哪些地方必须关闭资源。

先把一个概念说清楚:NIO 是 New I/O 的缩写,JDK 1.4 引入的一套新输入输出 API,核心是 Path、Files、Channel、Buffer。这一篇只讲文件部分,网络部分留到下一篇。日常读写文件,用 Path 加 Files 就够了,不需要直接操作 ByteBuffer。

Path 和 Files:先把「路径」当成对象

老的 java.io.File 把路径当成字符串,拼接、判断、规范化都得自己处理。NIO 的 Path 是不可变对象,提供 resolve(拼接)、normalize(去掉多余的点和斜杠)、relativize(求相对路径)、getParent、getFileName 这些方法。Files 则是配套的工具类,负责真正的读写、复制、移动、遍历。

Paths.get("a", "b", "c.txt") 会按当前平台的分隔符拼成路径,Windows 上是反斜杠,Linux 上是斜杠。不要自己在字符串里写死 "\\" 或 "/",换平台就会出问题。JDK 11 之后可以直接用 Path.of(...),写法更短,行为一样。

一次文件读取经过的层
Path 表示位置
Files 打开通道
按字符集解码
按行或按块读取
关闭资源

Path 只是「位置」,不保证文件存在。判断存在用 Files.exists,但要注意从判断到真正打开之间,文件可能被别人删掉,这叫检查与使用之间的竞争。更稳的做法是直接打开,捕获 NoSuchFileException,不要先判断再操作。

路径运算里最常用的是 resolve 和 relativize。base.resolve("logs") 得到子路径,base.resolve("logs").relativize(base.resolve("logs/a.txt")) 得到 a.txt。这两个方法都只做字符串层面的拼接和计算,不会访问磁盘,所以很快,也不会因为目录不存在而失败。需要真实路径时再调 toAbsolutePath 或 toRealPath。

字符集:默认 UTF-8,不代表文件是 UTF-8

JDK 18 起,默认字符集固定为 UTF-8,不再跟随操作系统的区域设置。本机跑出来也是 UTF-8:

System.out.println(Charset.defaultCharset());
UTF-8

这解决了很多跨平台乱码,但也带来一个新误会:很多人以为「默认 UTF-8」意味着「读什么文件都按 UTF-8」。文件是别人生成的,它可能是 GBK、可能是 UTF-8 带 BOM、可能是 Latin-1。默认值只在你没有显式指定字符集时生效,它不能替你判断文件真实编码。

更值得注意的是,Files.readString 在遇到非法字节时不会悄悄替换,而是直接抛异常:

Files.writeString(gbk, "你好,世界\n第二行\n", Charset.forName("GBK"));
try {
    Files.readString(gbk, StandardCharsets.UTF_8);
} catch (MalformedInputException e) {
    System.out.println(e.getClass().getSimpleName() + " / " + e.getMessage());
}
javac -encoding UTF-8 JavaNioDemo.java
java -Dstdout.encoding=UTF-8 -cp . JavaNioDemo

MalformedInputException / Input length = 1

这就是为什么有人读日志文件时突然看到 MalformedInputException,而换成 new String(bytes, UTF_8) 却只是得到一堆问号和方块。后者用的是宽松解码,遇到非法字节替换成 U+FFFD(替换字符)。两种行为没有对错,取决于你要「发现问题」还是「尽量读出内容」。本机实测,同一份 GBK 文件按 UTF-8 宽松解码,出现了 11 个替换字符。

正确的做法是知道文件来源,显式传字符集:Files.readString(path, Charset.forName("GBK")),或者 Files.newBufferedReader(path, charset)。写文件同理,Files.writeString 默认 UTF-8,要兼容老系统就得显式指定 GBK。

不要靠「读出来看看像不像中文」来判断编码。短文本、纯英文、数字较多的文件,多种编码解出来都「像」,猜错一次可能几周后才发现。编码信息应该来自文件来源、接口约定或文件头,不是靠肉眼。

UTF-8 和 GBK 的区别可以粗略理解为:UTF-8 用 1 到 4 个字节表示一个字符,ASCII 字符仍然占 1 字节,兼容英文世界的旧数据;GBK 用 1 到 2 个字节表示中文,是中文 Windows 环境的常见默认编码。一个纯中文的 GBK 文件按 UTF-8 读,几乎每个字节都会变成非法序列,替换字符成片出现;反过来,一个 UTF-8 文件按 GBK 读,可能出现「锟斤拷」这类典型乱码。两种方向都不要猜,显式指定才是正解。

如果必须在运行时转换编码,用 CharsetDecoder 和 CharsetEncoder 可以控制遇到非法输入时的策略:报错、替换或跳过。默认的 String 构造器使用替换策略,Files.readString 使用报错策略。知道这个差别,看到不同 API 对同一份坏文件给出不同结果时,就不会误以为文件本身变了。

BOM:看不见的三个字节

BOM 是 Byte Order Mark 的缩写,原本用于标记字节序,后来被 Windows 记事本等工具用来标记「这是 UTF-8」。它固定在文件开头,字节是 EF BB BF,解码后是一个 U+FEFF 字符。问题在于,很多解析器不认为它是「内容的一部分」,而 Java 的字符串读取会把它原样保留。

Files.write(bom, new byte[]{(byte)0xEF, (byte)0xBB, (byte)0xBF, 'a', 'b', 'c'});
String text = Files.readString(bom, StandardCharsets.UTF_8);
System.out.println(text.length());
System.out.printf("%04X%n", (int) text.charAt(0));
4
FEFF

文件内容只有 abc 三个字符,读出来长度却是 4,首字符编码是 FEFF。这多出来的一个字符,就是 CSV 第一列报「不存在」的原因。处理办法有三种:读进来后判断首字符是不是 \uFEFF 并去掉;用能自动识别 BOM 的解析库并显式开启;在入口处统一转成无 BOM 的 UTF-8。

反过来,写文件给 Windows 用户时,要不要加 BOM 取决于对方用什么软件打开。给 Excel 的 CSV 通常需要 BOM 才能正确识别 UTF-8;给程序解析的配置文件最好不要 BOM。这不是 Java 的规定,是使用场景的约定,写之前先问清楚。

另一个看不见的字符是换行符。Windows 用回车加换行两个字节,Linux 和 macOS 用一个换行字节。按行读取时 Java 会把三种换行都当成行边界,所以 Files.lines 通常不受影响;但如果你按字节处理、自己切分,或者把读到的行再原样写回,就可能出现多一个空行、少一个换行的问题。判断换行符同样要看字节,不要看编辑器里的显示。

还有一个容易混淆的参数:-Dfile.encoding 影响默认字符集,-Dstdout.encoding 影响控制台输出。程序读文件乱码,改 stdout.encoding 没用;控制台显示乱码,改 file.encoding 也未必有用。两个问题要分开看。

去掉 BOM 的代码很短,但要放在解析之前:if (!text.isEmpty() && text.charAt(0) == '\uFEFF') text = text.substring(1);。如果文件是流式读取的,就在拿到第一行时处理,别对每一行都判断。BOM 只可能出现在文件最开头,出现在中间说明文件被拼接坏了,那是另一个问题。

大文件:别把整个文件读进内存

Files.readAllBytes 和 Files.readString 都会把整个文件一次读进内存。读配置文件、小 JSON 没问题;读几百兆的日志、上 GB 的导出文件,就会直接把堆撑爆,表现为 OutOfMemoryError: Java heap space,而且往往发生在半夜跑批的时候。

StringBuilder sb = new StringBuilder();
for (int i = 1; i <= 100000; i++) sb.append("line ").append(i).append('\n');
Files.writeString(big, sb.toString());

try (Stream<String> lines = Files.lines(big)) {
    System.out.println(lines.count());
}
System.out.println(Files.readAllBytes(big).length);
100000
1088895

这份测试文件 10 万行,大约 1MB。Files.lines 返回一个按行读取的流,是懒加载的:调用 count 才开始读,读完一行处理一行,内存里不会同时存在整个文件。它适合「逐行处理、不回头」的场景,比如过滤日志、转换格式、统计行数。

整文件读取

readAllBytes、readString、readAllLines。写法最短,拿到完整内容后可以随意查找、排序、反复遍历。代价是内存占用和文件大小成正比,超过数组上限或堆上限直接失败。

流式读取

Files.lines、BufferedReader、InputStream。内存占用和文件大小无关,只和缓冲区有关。只能顺序读、不能回头,而且必须关闭,否则句柄泄漏。

选择标准不是「哪个更高级」,而是「处理完这一行之后还需不需要看别的行」。需要全局排序、去重、关联,就先读进内存,但要确认大小;只需要逐行转换、过滤、写出去,就用流式。拿不准时先看文件大小,再决定。

关键在 try-with-resources 的括号。Files.lines 打开的流持有文件句柄,不关闭就泄漏。Windows 上文件被占用时删不掉、改不了,排查半天才发现是某个流没关。只要流的类型实现了 AutoCloseable,就放在 try 的括号里,不要靠垃圾回收。

需要更细的控制时,用 Files.newBufferedReader(path, charset) 或 Files.newInputStream。BufferedReader 可以按行读,也可以按字符块读;InputStream 可以按字节读,适合二进制文件。Files.copy 和 InputStream.transferTo 适合整文件复制,内部会分块搬运,不会一次性分配整个文件大小的缓冲。

缓冲区不是越大越好。默认的 8KB 到 16KB 对大多数文本已经够用,盲目调到几 MB 只会在并发读多个文件时放大内存占用。真正影响大文件吞吐的是「一次读多少、处理多久」,如果每读一行就发一次网络请求,瓶颈在请求而不在缓冲区。

还有一种常见需求是「只读前面几行」或「从中间某行开始读」。前者可以用 Files.lines 加 limit,后者需要 RandomAccessFile 或 FileChannel.position,按字节定位。按字节定位要自己处理字符边界,别在半个汉字中间切开,否则解码会失败。

目录遍历与路径安全

Files.walk 从某个目录开始递归遍历,返回一个 Stream<Path>。它同样是懒加载的,也必须关闭。遍历大目录时不要用 collect 把所有路径攒在内存里,边遍历边处理,或者用 Files.find 带上过滤条件。

try (Stream<Path> walk = Files.walk(dir)) {
    System.out.println(walk.filter(Files::isRegularFile).count());
}
3

遍历默认不跟随符号链接,这是安全的选择:跟随链接可能绕进循环目录,也可能读到预期之外的系统路径。确实需要跟随时有专门参数,但要想清楚后果。删除目录也不能直接 Files.delete,非空目录会抛 DirectoryNotEmptyException,正确做法是先遍历文件、按深度倒序删,或者用 Files.walkFileTree 在访问完目录时删。

路径安全是另一个高频问题。用户上传文件时,如果把原始文件名直接拼进目录,攻击者可以传一个叫 ../../windows/system.ini 的名字,写到程序目录之外。下面这段代码演示了拼接和归一化的结果:

Path root = dir.resolve("uploads");
Path evil = root.resolve("..").resolve("..").resolve("windows").normalize();
System.out.println(evil);
System.out.println(evil.startsWith(root));
C:\Users\c1805\AppData\Local\Temp\windows
false

normalize 只是把 .. 展开,它不会阻止你跳出目录。安全检查的正确做法是:归一化之后判断结果是否仍在允许的根目录内(startsWith(root)),不满足就拒绝。更严格的做法是用 toRealPath 解析真实路径后再判断,防止符号链接绕过。另外,不要只信扩展名,文件名里的空字节、大小写差异、Unicode 相似字符都要考虑。

目录操作还有几个常用但容易忽略的点。Files.createDirectories 会连同不存在的父目录一起创建,Files.createDirectory 只建最后一层,父目录不存在就抛异常。Files.createTempFile 和 Files.createTempDirectory 能生成带随机后缀的临时路径,适合「先写临时文件再原子替换」的流程。读权限、大小、修改时间用 Files.getAttribute 或 Files.readAttributes,不要用 File.length() 那种旧写法混着用。

如果遍历逻辑比较复杂,比如「进入目录前做权限判断、出错时跳过而不是中断」,Files.walkFileTree 比 Files.walk 更合适。它让你实现 FileVisitor 的三个回调:进入目录、访问文件、离开目录。好处是每一步都能控制,坏处是代码更长。简单的过滤统计用 walk,需要精细控制再用 walkFileTree。

出问题时先看哪里

现象真实原因第一步查什么
中文显示成问号或方块读取时用的字符集和文件实际编码不一致确认文件来源编码;用十六进制看开头字节,显式传 Charset
读文件抛 MalformedInputExceptionFiles.readString 使用严格解码,遇到非法字节直接失败看文件真实编码;需要容错就改用宽松解码并记录替换字符
CSV 第一列名多了看不见的字符文件开头有 UTF-8 BOM,被当成第一个字符看首字符是不是 U+FEFF;读取后剥掉 BOM
OutOfMemoryError 发生在读文件时用了 readAllBytes 或 readAllLines,整文件进内存看文件大小;改成 Files.lines 或 BufferedReader 逐行处理
Windows 上文件删不掉、改不了某个流或通道没有关闭,文件句柄还被占用检查 Files.lines、newBufferedReader 是否放在 try-with-resources 里
NoSuchFileException 与 AccessDeniedException 分不清前者是路径不存在,后者是权限或文件被占用打印绝对路径;确认运行账号权限;不要只捕获一个大类异常
遍历目录漏文件或数量不对默认不跟随符号链接,或遍历深度不够看 walk 的深度参数;确认是否需要跟随链接
上传路径能写到目录外用原始文件名拼接路径,.. 没有被拦截归一化后判断 startsWith(root);必要时用 toRealPath
写文件后原内容消失Files.write 默认是覆盖截断,不是追加看是否传了 StandardOpenOption.APPEND;确认写入模式

排查文件问题的顺序建议固定:先打印绝对路径,确认操作的是不是你以为的那个文件;再看文件大小和开头字节,确认编码与 BOM;最后看资源有没有关闭。三步走完,大部分「玄学」问题都能落地。

边界与代价

NIO 的文件 API 比老的 File 清楚很多,但它不是银弹,限制要提前知道:

  • 编码必须由调用方负责:Java 不会自动猜编码,也没有可靠的通用检测算法。来源不明时,只能在边界处做一次转换,并把编码记录进日志。
  • 整文件 API 有内存上限:readAllBytes 返回的数组长度是 int,文件超过约 2GB 直接失败;即使没到上限,堆也可能先撑不住。
  • 流和目录遍历都要关闭:Files.lines、Files.walk、Files.list 都持有系统资源,忘记关闭在 Windows 上会锁文件,在 Linux 上会耗尽句柄。
  • 文件系统行为有平台差异:路径大小写、分隔符、文件锁、符号链接、权限模型都不一样。本地开发通过,不代表部署到 Linux 容器里也通过。
  • 写入不是原子的:直接覆盖目标文件时,进程崩在中间会留下半个文件。重要文件先写临时文件,再用 Files.move 加原子移动替换。
  • NIO 的高性能通道需要自己管缓冲:FileChannel 加 ByteBuffer 能做零拷贝和内存映射,但缓冲区的分配、清理、边界处理都要自己来,普通业务没必要上。
  • 删除和替换有平台语义:Files.delete 删不掉非空目录或正被打开的文件;Files.move 跨文件系统时可能退化成复制加删除,不再是原子操作。需要原子替换时确认源和目标在同一个文件系统上。

还有一个现实约束:容器里的文件系统往往是临时的。容器重启,写进容器层的文件就没了。需要持久化的数据要放到挂载卷或对象存储,这不是语言能解决的问题,但排查「文件明明写了却不见了」时必须先想到它。文件系统的目录结构、权限和挂载机制,在 操作系统:文件系统 里有更完整的说明。

当天能自己验证的练习

  1. 用 GBK 写一个含中文的文件,再分别用 Files.readString 和 new String(bytes, UTF_8) 读,记录一次抛异常、一次产生替换字符的差别。
  2. 写一个开头带 EF BB BF 的文件,读成字符串后打印长度和首字符编码,确认首字符是 FEFF,再写代码把它去掉。
  3. 生成一个 10 万行的文本文件,分别用 Files.readAllBytes 和 Files.lines 统计行数,观察内存占用和写法的差别。
  4. 故意不关闭 Files.lines 返回的流,在 Windows 上尝试删除该文件,记录失败现象;再改成 try-with-resources 后重试。
  5. 构造一个包含 .. 的文件名,拼到上传目录下,打印归一化路径和 startsWith 的结果,确认安全检查为什么必须做。

小结

三句话收一下:Path 表示位置、Files 负责读写,路径拼接要用 API,不要手写分隔符;字符集必须显式传,Files.readString 遇到非法字节会抛异常,BOM 会变成一个真实字符;大文件用流式读取并放在 try-with-resources 里,目录遍历和上传路径都要做边界检查。

下一篇讲网络通信:HttpClient 和 Socket。文件是「本地资源」,网络是「远端资源」,但两者的共同点是都必须关闭、都必须设超时。今天学到的 try-with-resources 和资源泄漏排查,会直接用在下一篇的响应体和连接上。