Java Files.readString 读取 UTF-8 配置乱码：BOM、字符集与首字符排查

配置文件明明保存成了 UTF-8，Java 用 Files.readString 读出来却在第一个键名前多了一个看不见的字符，甚至导致 JSON 解析失败。这个现象通常不是文件内容被破坏，而是 UTF-8 BOM（字节序列 EF BB BF）被当成了普通文本的一部分。

先复现：乱码不一定来自中文内容

我们先准备一个很小的配置文件，用支持BOM的编辑器保存下面的内容，文件开头保留UTF-8 BOM标识：

{"timeout": 1500, "region": "cn"}

直接用Files.readString读取的时候，打印日志往往只能看到正常的花括号和键名，隐藏的问题得专门检查读取结果的第一个字符才能发现：

Path path = Path.of("config.json");
String text = Files.readString(path, StandardCharsets.UTF_8);

System.out.println(text);
System.out.println((int) text.charAt(0));
System.out.println(text.startsWith("{"));

如果最后一行是 false，而首字符码点是 65279，就已经抓到 U+FEFF 了。它不是乱码方块，也不会总能在日志里显眼地显示出来。

Files.readString 的字符集边界在哪里

Files.readString(path) 适合快速读取文本，但工程代码更应该把字符集写在调用点。这样代码不会随着操作系统默认字符集变化而改变行为：

String text = Files.readString(
    Path.of("config.json"),
    StandardCharsets.UTF_8
);

显式指定 UTF-8 只能解决“用什么方式把字节解码成字符”的问题，不能自动替你决定是否丢弃文件开头的 BOM。也就是说，编码选对了，U+FEFF 仍然可能保留下来。

排查步骤可以拆成三个逐层校验的判断：

• 文件前 3 个字节是否为 EF BB BF；
• 解码后的第一个字符是否为 \uFEFF；
• 解析器抛出的报错位置是否刚好落在第一个键名处，也就是文件开头的位置。

最小修复：只清理开头的 BOM

输入来自用户上传、跨平台配置仓库或第三方导出工具时，可以把 BOM 清理封装在读取边界，而不是在业务字段里到处调用 replace：

static String readUtf8WithoutBom(Path path) throws IOException {
    String text = Files.readString(path, StandardCharsets.UTF_8);
    if (!text.isEmpty() && text.charAt(0) == '\uFEFF') {
        return text.substring(1);
    }
    return text;
}

这里要注意两个细节。第一，先判断读取到的字符串是否为空，避免无意义的下标访问报错；第二，只检查索引为0的第一个字符。配置正文中本身合法出现的零宽字符不能做全局删除，否则这个修复动作会在用户无感知的情况下篡改原本的业务数据。

不要把三个相似现象混成一个问题

默认字符集不一致

如果同一个文件在两台机器上出现中文乱码，优先检查是否使用了默认字符集。解决方式是统一文件约定并在 API 调用中传入 StandardCharsets.UTF_8。这类问题通常影响整段文字，不只影响第一个字符。

UTF-8 BOM 留在开头

如果中文显示正常，只有 JSON 解析、首键比较或配置签名失败，且首字符是 U+FEFF，应按 BOM 问题处理。它常见于编辑器保存、脚本导出和不同系统之间的文件交换。

文件本身包含不可见控制字符

如果清理BOM之后问题还没解决，就把整个文件导出成十六进制格式，查看文件开头和报错附近的原始字节，不要随意扩大字符串替换的范围。其余的排查方向还包括不可见的控制字符、错误的换行格式转换、文件本身被截断这三类常见情况。

放进 JSON 配置读取器时怎么验收

写单元测试的时候建议同时覆盖“无BOM”和“带BOM”两种输入场景，并且校验后续的业务解析结果，不要只验证readString读取方法本身没有抛出异常：

String text = readUtf8WithoutBom(Path.of("config.json"));
assert text.charAt(0) == '{';
assert text.contains("\"timeout\"");
// 再交给 JSON 解析器，并断言 timeout == 1500

生产环境的日志不需要打印完整的配置内容，只需要记录文件来源、字节长度、是否检测到BOM、解析失败的位置就足够了。如果配置文件里存放了密钥这类敏感信息，要绝对避免把原文内容直接写入日志。

常见问题

Files.readString 会自动识别 UTF-8 BOM 吗？

不要依赖自动识别来定义业务契约。显式指定 UTF-8 后，仍应根据输入来源决定是否在读取边界清理开头的 U+FEFF。

为什么肉眼看不见 BOM，JSON 却解析失败？

BOM 是不可见字符。它位于第一个键名前时，解析器看到的并不是预期的 { 或键名，所以错误位置常常指向文件开头。

能不能直接对全文调用 replace("\\uFEFF", "")？

不建议这么做。全局替换会无差别改动正文里的业务数据，正确的处理边界是只检查并且移除字符串的第一个字符。

结论：把编码约定和清理动作固定在文件入口

Files.readString 负责把字节解码为字符串，BOM 是否保留则是输入规范和读取策略的问题。显式使用 UTF-8、检查首字符、用有无 BOM 的双样本做解析验收，通常就能把这类“看起来像乱码”的故障稳定定位下来。