Java文件编码检测：BOM、严格解码与CI卡口

简介：EncodingChecker 是一份面向 Java 开发者的文件编码检查与转换工具源码包，重点解决多编码文本识别、BOM 判断及编码互转问题，适合需要处理 GBK、US-ASCII、ISO-8859-1 以及 UTF-8/16/32 大小端与有无 BOM 等场景的开发者学习和复用。压缩包共 27 个文件，主体为 23 个 Java 源码文件，另含 2 个 XML 配置、1 个 Markdown 说明和 1 个 PPTX 讲义，整体约 599KB，结构轻量，便于阅读实现与二次改造。已有 283 人学习下载，说明其在编码排查与工具开发方面具有一定参考价值。读者可从中了解编码检测流程、转换逻辑与常见 BOM 差异处理思路，并借助说明文档和演示材料快速理解项目组织方式，为实际项目中的乱码定位、批量转码和编码规范校验提供可借鉴的实现基础。

1. 文件编码检查器 encodingchecker：先把手里的乱码问题说清楚

接手别人留下的项目，最先让人怀疑人生的往往不是架构，而是打开一个.properties文件满屏的「锟斤拷」。同一套代码，源码目录是 GBK，配置文件被某个编辑器存成了 UTF-8 带 BOM，日志又是 GB18030，混在一起跑，问题只在特定机器上冒出来。encodingchecker 就是冲着这个场景写的一个 Java 文件编码检查器：给它一个目录，它逐个文件判 BOM、做严格解码试探、给置信度打分，最后吐一份 CSV 报告。它不负责转码，只回答「这个文件到底是什么编码、有多确定」。适合要接手遗留系统、做代码库迁移、或者想给 CI 加一道编码卡口的人。

2. 判定链路：BOM、严格解码器与置信度打分

编码检测这件事在理论上是不保真的——同一段字节序列在多种编码下都能解释成「合法」的字符，所以任何工具给出的都是概率而非事实。一个能用的检测器，价值不在于算法多玄学，而在于它清楚自己什么时候不确定，并且把这个不确定量化成置信度交给调用方。encodingchecker 的判定是一条三段式链路：先看 BOM，BOM 没有就走严格解码试探，试探出多个候选再用启发式打分排序。这个顺序不是随便排的，每一步都在缩小搜索空间，同时尽量不引入误判。

2.1 先看 BOM：五种字节前缀的顺序陷阱

BOM 是整条链路里唯一能给出 100% 确定结论的信号，因为它是文件里显式写下的编码声明，不需要靠统计去猜。检测器读文件头部 4 个字节就够了，但读法和判断顺序经常被写错。

public final class BomDetector { /** 返回 null 表示没有 BOM，需要走后续试探 */ public static Charset detect(byte[] head, int len) { // 4 字节的 UTF-32 必须先判，否则 FF FE 会被误认成 UTF-16LE if (len >= 4) { if (head[0] == 0x00 && head[1] == 0x00 && (head[2] & 0xFF) == 0xFE && (head[3] & 0xFF) == 0xFF) { return Charset.forName("UTF-32BE"); } if ((head[0] & 0xFF) == 0xFF && (head[1] & 0xFF) == 0xFE && head[2] == 0x00 && head[3] == 0x00) { return Charset.forName("UTF-32LE"); } } if (len >= 3 && (head[0] & 0xFF) == 0xEF && (head[1] & 0xFF) == 0xBB && (head[2] & 0xFF) == 0xBF) { return StandardCharsets.UTF_8; } if (len >= 2) { if ((head[0] & 0xFF) == 0xFE && (head[1] & 0xFF) == 0xFF) { return StandardCharsets.UTF_16BE; } if ((head[0] & 0xFF) == 0xFF && (head[1] & 0xFF) == 0xFE) { return StandardCharsets.UTF_16LE; } } return null; } public static int lengthOf(Charset cs) { String n = cs.name(); if (n.startsWith("UTF-32")) return 4; if (n.startsWith("UTF-16")) return 2; return 3; // UTF-8 } }

这段代码里唯一需要动脑子的地方就是判断顺序。FF FE 00 00的前两个字节FF FE和 UTF-16LE 的 BOM 完全一样，如果先判两字节分支，UTF-32LE 就会被吃掉，后面的内容按 UTF-16LE 解码会得到一堆夹杂空字符的乱码。所以四字节分支必须前置，这是常见的血泪经验，抄代码的时候别顺手调换。

head[i] & 0xFF这个写法是为了避免 Java 里 byte 的符号扩展：0xEF作为 byte 是负数，直接和 int 比较会得到错误结果。这个坑在任何字节级处理里都会出现，属于必须养成的肌肉记忆。

BOM 检测完之后还有一步容易被忽略：记录 BOM 长度，后续扫描内容和输出报告时要把头部的这几个字节跳过。否则 UTF-8 BOM 会被当成三个普通字节参与统计，让原本纯净的 ASCII 文件被打上「含非 ASCII」的标签。

2.2 严格解码器：把「不报错」变成「可判定」

没有 BOM 的时候，绝大多数人第一反应是new String(bytes, charset)，然后判断有没有出现乱码。这个做法在检测场景下是彻底失败的，因为String的构造函数内部用的CharsetDecoder默认行为是CodingErrorAction.REPLACE——遇到非法字节就静默替换成U+FFFD，从不抛异常，也从不告诉你替换了多少个。你以为在检测，其实只是拿到了一个被悄悄污染过的字符串。

正确做法是显式构造一个把错误当错误处理的解码器：

public final class StrictProbe { private final CharsetDecoder decoder; private final CharBuffer sink = CharBuffer.allocate(16 * 1024); private boolean failed; public StrictProbe(Charset cs) { this.decoder = cs.newDecoder() .onMalformedInput(CodingErrorAction.REPORT) // 非法字节序列 -> 报错 .onUnmappableCharacter(CodingErrorAction.REPORT); // 无法映射字符 -> 报错 } /** * 增量喂入字节，返回 false 说明这段序列在该编码下不合法。 * endOfInput=false 时允许缓冲区尾部残留半个多字节字符。 */ public boolean feed(ByteBuffer in, boolean endOfInput) { if (failed) return false; while (true) { CoderResult r = decoder.decode(in, sink, endOfInput); sink.clear(); if (r.isUnderflow()) return true; if (r.isOverflow()) continue; // 输出区满了，清空后继续 failed = true; // malformed / unmappable return false; } } public boolean finish(ByteBuffer tail) { return feed(tail, true) && decoder.flush(sink).isUnderflow(); } }

这里几个参数值得展开说。CodingErrorAction.REPORT是关键，它让decode在遇到非法输入时返回CoderResult.isMalformed()而不是继续替换；onUnmappableCharacter管的是另一类问题——字节序列本身合法、但目标字符集里没有对应字符，在检测场景下同样应该算失败。sink的作用只是消耗解码输出，它的内容对判定没有意义，所以每次循环都clear()掉，分配 16KB 是为了减少isOverflow()的触发次数。

feed和finish分开是因为流式扫描时不能假设每次读到的块刚好落在字符边界上。UTF-8 的一个汉字占 3 字节，缓冲区边界完全可能把它劈成 1+2，中间那次decode会返回isUnderflow()并且把剩余字节留在ByteBuffer里，调用方需要用compact()保留下来，等下一块拼齐再喂。这个细节在 3.2 节里会用完整代码演示。

用它判 UTF-8 就三行：

ByteBuffer buf = ByteBuffer.wrap(sampleBytes); StrictProbe probe = new StrictProbe(StandardCharsets.UTF_8); boolean isUtf8 = probe.finish(buf);

返回 false 就说明这段字节里存在非法的 UTF-8 序列，可以排除。返回 true 也不能直接下结论——纯 ASCII 内容在任何 ASCII 兼容编码下都合法，一万个英文字母组成的文件在 UTF-8、GBK、ISO-8859-1 下全都通过。这就是下一节要处理的问题。

2.3 GB18030 兜底与置信度打分

国内环境里最常见的第二种编码是 GBK 及其超集 GB18030。这两个编码的关系必须先搞清楚，否则判定顺序会写反：GB18030 是 GBK 的严格超集，任何合法的 GBK 字节序列在 GB18030 下都合法，但反过来不成立——GB18030 的四字节序列（首字节0x81-0xFE，第二字节0x30-0x39，第三字节0x81-0xFE，第四字节0x30-0x39）在 GBK 里是非法的。所以试探顺序必须是先 GBK 后 GB18030，先用更严格的那个排除，剩下的才归给超集。

public final class CharsetResolver { private static final Charset GBK = Charset.forName("GBK"); private static final Charset GB18030 = Charset.forName("GB18030"); public static Candidate resolve(ByteBuffer sample) { // 1) UTF-8 严格试探 ByteBuffer copy = sample.duplicate(); if (new StrictProbe(StandardCharsets.UTF_8).finish(copy)) { double s = score(StandardCharsets.UTF_8, sample.duplicate()); return new Candidate(StandardCharsets.UTF_8, s); } // 2) GBK 严格试探（比 GB18030 严格） copy = sample.duplicate(); if (new StrictProbe(GBK).finish(copy)) { double s = score(GBK, sample.duplicate()); return new Candidate(GBK, Math.max(s, 0.75)); } // 3) GB18030 兜底 copy = sample.duplicate(); if (new StrictProbe(GB18030).finish(copy)) { double s = score(GB18030, sample.duplicate()); return new Candidate(GB18030, Math.max(s, 0.7)); } return new Candidate(null, 0.0); } private static double score(Charset cs, ByteBuffer buf) { String text = cs.decode(buf).toString(); HeuristicScorer sc = new HeuristicScorer(); sc.accept(text); return sc.score(); } }

sample.duplicate()每次都要复制一份，因为decode会推进 position，不复制的话第二次试探拿到的是空缓冲区，这是个很容易写出来的低级错误，而且症状很迷惑——所有文件都被判成第一种编码。

打分器本身不复杂，核心是统计字符构成：

public final class HeuristicScorer { private int cjk, ascii, ctrl, replacement, other; public void accept(CharSequence s) { for (int i = 0; i < s.length(); i++) { char c = s.charAt(i); if (c < 0x80) { if (c == '\t' || c == '\n' || c == '\r' || c >= 0x20) ascii++; else ctrl++; // 除制表/换行外的控制字符 } else if (c == '\uFFFD') { replacement++; } else if ((c >= 0x4E00 && c <= 0x9FFF) // CJK 统一表意文字 || (c >= 0x3000 && c <= 0x303F) // CJK 标点 || (c >= 0xFF00 && c <= 0xFFEF)) { // 全角字符 cjk++; } else { other++; } } } public double score() { int total = cjk + ascii + ctrl + replacement + other; if (total == 0) return 0.0; double s = (double) (cjk + ascii) / total; s -= 5.0 * ctrl / total; // 控制字符重罚 s -= 10.0 * replacement / total; // 替换符更重罚 return Math.max(0.0, Math.min(1.0, s)); } }

这个打分函数的含义是：CJK 字符和可打印 ASCII 占比越高越可信，控制字符和U+FFFD越多越可疑。权重设成 5 和 10 不是拍脑袋——一个 10KB 的文件里出现 200 个随机控制字符，基本可以断定编码判错了，而 1 个U+FFFD在 1MB 文件里可能只是偶然，按比例罚分能自动适配文件大小。

这里有个必须提前向使用者交代的边界：

注意：纯 ASCII 文件无法被任何检测器判定为「UTF-8」或「GBK」，它同时属于两者。这类文件的输出应该标注为ASCII，置信度给 1.0，但附一条说明「仅含 ASCII 字符，任何 ASCII 兼容编码均可正确读取」。如果直接把 GBK 标签打给它，后面按 GBK 转 UTF-8 也不会出错，但报告本身就是在撒谎。

3. 把检测器跑起来：CLI 扫描、流式读取与报告落地

判定链路只是一组静态方法，真正拿来干活需要一层壳：命令行参数、目录遍历、文件过滤、结果输出。这层壳的代码量比检测本身大，但决定了工具能不能接进日常工作流。设计目标很明确——一条命令扫完一个仓库，产出一份可以直接丢进表格软件的报告，并且用退出码告诉 CI 有没有问题。

3.1 命令行参数与目录扫描骨架

参数设计上刻意保持少，只留真正会改的几项：

入口方法不复杂：

public static void main(String[] argv) throws IOException { Options opt = Options.parse(argv); List<Path> files; try (Stream<Path> s = Files.walk(opt.root)) { files = s.filter(Files::isRegularFile) .filter(p -> !opt.isExcluded(p)) // 跳过 target / node_modules 等 .filter(opt::matchesExtension) .sorted() .collect(Collectors.toList()); } int suspicious = 0; try (ReportWriter writer = new ReportWriter(opt.report)) { for (Path p : files) { Verdict v = new FileChecker(opt.maxSampleBytes).check(p); writer.write(p, v); if (v.charset() == null || v.confidence() < opt.minConfidence) { suspicious++; } } } // 退出码约定见 3.3 节 System.exit(suspicious == 0 ? 0 : 1); }

Files.walk用 try-with-resources 包住是必须的，它内部持有目录句柄，不关闭在扫描大仓库时会把文件描述符耗光。sorted()看起来无关紧要，但报告要能 diff——同一个仓库两次扫描的行序必须稳定，否则每次 CI 跑完报告都是全红，根本没法看。

排除目录这一步建议默认就带上target、build、node_modules、.git、dist。这些目录里的文件要么是编译产物、要么是三方依赖，一旦它们被卷进报告，几千行「不确定」会把真正需要处理的那几十个源文件淹掉。

3.2 大文件流式读取：分块解码与跨块字符

Files.readAllBytes写起来最省事，但一个 2GB 的日志文件能直接把堆打爆。更现实的问题是，编码统计根本不需要读完整文件——前 1MB 的字符分布已经足够稳定，后面再读只是浪费 IO。所以扫描器要同时满足两点：按块读取，并且在块边界正确拼接多字节字符。

public final class FileChecker { private static final int BLOCK = 64 * 1024; private final int maxSampleBytes; public FileChecker(int maxSampleBytes) { this.maxSampleBytes = maxSampleBytes; } public Verdict check(Path file) throws IOException { try (FileChannel ch = FileChannel.open(file, StandardOpenOption.READ)) { // 1) 读头 4 字节判 BOM ByteBuffer head = ByteBuffer.allocate(4); while (head.hasRemaining() && ch.read(head) > 0) { /* 尽力读满 */ } Charset bom = BomDetector.detect(head.array(), head.position()); ByteBuffer body = ByteBuffer.allocate(BLOCK); ByteBuffer sample = ByteBuffer.allocate(Math.min(maxSampleBytes, 4 * 1024 * 1024)); StrictProbe probe = new StrictProbe(StandardCharsets.UTF_8); boolean utf8Ok = true; if (bom != null) { ch.position(BomDetector.lengthOf(bom)); // 跳过 BOM，避免污染统计 } else { ch.position(0); } int read; int scanned = 0; while (scanned < maxSampleBytes && (read = ch.read(body)) > 0) { body.flip(); scanned += read; // 采样一份用于打分 int keep = Math.min(body.remaining(), sample.remaining()); ByteBuffer dup = body.duplicate(); dup.limit(dup.position() + keep); sample.put(dup); // 严格试探，注意 compact 保留跨块残余 if (utf8Ok && !probe.feed(body, false)) { utf8Ok = false; } body.compact(); // 关键：把不足一个字符的残余字节挪到 buffer 开头 } // 收尾：把最后残留的字节按 endOfInput=true 处理 body.flip(); if (utf8Ok && !probe.finish(body)) { utf8Ok = false; } sample.flip(); return judge(file, bom, utf8Ok, sample); } } }

body.compact()这行是整段代码的核心。它做了两件事：把position到limit之间的未消费字节搬到缓冲区开头，然后把position设为剩余字节数、limit设为容量。于是下一轮ch.read(body)会紧接着残余字节继续写，原来被劈开的半个汉字就和下一块的前半截拼上了。没有这一步，任何一个横跨 64KB 边界的多字节字符都会被误判成非法序列，症状是「同一个文件每次扫描结果不一样」，非常折磨人。

probe.finish(body)是另一个容易漏掉的收尾。循环内的feed(body, false)允许尾部残留不完整序列，但如果文件真就以半个字符结尾（截断的文件，或者编码本来就判错了），不调用finish就会把这个错误吞掉。只有以endOfInput=true再喂一次，解码器才会把残留字节报成MALFORMED。

sample缓冲区设了 4MB 上限，是因为打分本身也需要控制内存。实际使用时maxSampleBytes默认 1MB，sample永远不会填满，这个上限只是防御性写法。

judge方法把前面几节的结论合起来：

private Verdict judge(Path file, Charset bom, boolean utf8Ok, ByteBuffer sample) { if (bom != null) { return new Verdict(bom, 1.0, true, "BOM"); } Candidate c = CharsetResolver.resolve(sample); return new Verdict(c.charset(), c.score(), false, c.charset() == null ? "none" : "heuristic"); }

BOM 分支直接给 1.0，因为那是显式声明；启发式分支的置信度来自 2.3 节的打分函数，通常落在 0.7 到 0.98 之间。低于 0.8 的文件在报告里应该被标黄，它们才是需要人工看一眼的那批。

3.3 报告输出：CSV 字段与退出码约定

报告是给两类读者看的：人眼扫一遍找异常，脚本读进去做后续处理。所以 CSV 的列要稳定、要有机器可判读的枚举值，别塞太多自然语言。

lineEnding这一列不属于编码检测的核心，但成本极低——扫样本的时候顺便统计\r\n、单独的\n、单独的\r出现次数就能得出来。它的价值在后面做转码时体现：把 GBK 转成 UTF-8 的时候如果顺手把 CRLF 归一成 LF，Git 上会冒出一整片「文件被全量修改」的 diff，审查的人会想打人。有这个列在，转码工具就知道该不该保留原行尾。

退出码约定成三档：

// 0：所有文件都有明确判定且置信度达标 // 1：存在 UNKNOWN 或置信度低于阈值（CI 应当失败） // 2：参数错误或 IO 异常（与内容无关的失败） System.exit(suspicious == 0 ? 0 : 1);

档位分开的意义在于 CI 里能区分「代码有问题」和「工具跑挂了」。前者要开发者去修文件，后者要运维去看环境，混成一个非零码会让排查方向完全跑偏。

4. 避坑与常见问题：五个翻车现场的现象、原因与解决

编码检测这个领域的坑有个共同特征：出错的时候不报错，只是安静地给出一个错误答案。所以下面这几条都按「现象 → 原因 → 解决」写，重点放在怎么从症状反推到根因。

4.1 判定环节的三个坑

坑一：所有文件都被判成 UTF-8，包括明明是 GBK 的源码。

现象是扫描一份确定用 GBK 存的中文源码，报告里charset全写UTF-8，confidence还挺高，但打开文件依然是乱码。原因通常有两个：一是用了new String(bytes, charset)做试探，REPLACE模式把非法字节悄悄换成了U+FFFD，试探永远返回成功；二是虽然用了CodingErrorAction.REPORT，但捕获异常的位置写错了，异常被外层catch (Exception e) {}吞掉，逻辑继续往下走。前者要改成显式构造CharsetDecoder并设置REPORT，后者要保证MalformedInputException只被当成「该编码不匹配」这一个语义处理，别和 IO 异常混在一个 catch 块里。

坑二：短文件和纯英文文件被判成随机编码，每次跑结果还不一样。

现象是同一个只有几行key=value的英文配置文件，第一次报ASCII，删掉一行后报GBK，再加一行又变成UTF-8。原因是这类文件的信息量根本不足以区分编码——在字节层面，它们在任何 ASCII 兼容编码下都合法，判定完全由打分函数的浮点噪声决定。解决办法是在判定前先做一次「是否全为 ASCII」的快速检查：如果样本里所有字节都小于0x80，直接返回ASCII且置信度 1.0，不进入后续试探。这一步能把大量噪音从报告里清掉，也让真正需要关注的 GBK/UTF-8 冲突文件浮出来。

坑三：GBK 文件被报成 GB18030，或者反过来。

现象是报告里一堆 GB18030，但实际把它们按 GB18030 转码后，某些生僻字变成了别的字。原因是判定顺序写反了。GB18030 是 GBK 的超集，把一段 GBK 字节喂给 GB18030 解码器，它一定返回成功，所以凡是先试 GB18030 的实现，GBK 文件全都会被超集吞掉。正确的顺序是先 GBK 严格试探，通过就判 GBK；不通过再试 GB18030，只有包含四字节序列的文件才会落到这一支。转过来还有个隐性风险：用 GB18030 解码 GBK 内容，绝大多数情况下字符是对的，因为两者在双字节区完全兼容，只有在极少数扩展区才有差异——这种「大部分时候对」的错误最难被发现。

4.2 工程落地环节的两个坑

坑四：大文件扫描时随机报「非法 UTF-8」，小文件却正常。

现象是同一个源文件用编辑器打开完全正常，检测器读到 64KB 边界附近就报 malformed。原因就是 3.2 节讲的跨块截断——缓冲区边界把一个三字节的汉字劈成了两半，前半截留在上一块的尾部，如果实现里没做compact()保留，下一次decode就会拿半截字节去匹配，必然失败。解决方式是严格用增量解码接口：循环内endOfInput=false，每轮结束ByteBuffer.compact()，循环外再用endOfInput=true收尾一次。顺带提一句，块大小设成 3 或 4 的整数倍并不能规避这个问题，因为 GB18030 是变长的双字节和四字节混合，任何固定块大小都可能切在字符中间。

坑五：BOM 检测出来了，但转码之后文件第一行匹配不上。

现象是检测报告里bom=true，后续按 UTF-8 读取并解析properties，第一行的 key 死活取不到，打印出来的字符串看起来还正常。原因是 BOM 的三个字节被当成内容解码成了U+FEFF，这是个零宽度的不可见字符，肉眼完全看不出来，但它实实在在占据字符串的第一个位置。解决办法有两层：检测阶段记录bom=true并在后续处理中跳过前 3 字节；转码阶段显式决定是保留还是剥离 BOM，并在报告的note里写清楚。默认建议剥离——UTF-8 本来就不需要 BOM，保留它只会让下游的解析器各自为战。

5. 批量转换与回归验证：从「查出来」到「改对」

检测出编码只是第一步，真正的工作量在后面：把几百个 GBK 文件转成 UTF-8，还得保证转完之后内容一个字都没变。这件事最怕的不是转错，而是转错了没人知道——文件还在，能打开，看起来也正常，只是某个生僻字变成了问号。所以转换流程必须带上回读校验，并且用带标签的语料做一次准确率回归，把检测器本身的误判率量化出来。

5.1 检测—转换—回读校验的三步闭环

转换的单文件逻辑不长，但每一步都有讲究：

public final class Transcoder { /** * @param from 检测阶段给出的源编码，不允许为 null * @param stripBom true 表示输出不带 BOM * @return 转换后的字符数，用于交叉校验 */ public static int toUtf8(Path src, Path dst, Charset from, boolean stripBom) throws IOException { byte[] raw = Files.readAllBytes(src); // 1) 严格解码，任何非法序列直接抛出，不做替换 CharsetDecoder dec = from.newDecoder() .onMalformedInput(CodingErrorAction.REPORT) .onUnmappableCharacter(CodingErrorAction.REPORT); String text = dec.decode(ByteBuffer.wrap(raw)).toString(); // 2) 剥离源文件可能存在的 BOM 字符（不是字节，是解码后的 U+FEFF） if (stripBom && !text.isEmpty() && text.charAt(0) == '\uFEFF') { text = text.substring(1); } // 3) 以 UTF-8 写出，先写临时文件再原子替换 byte[] out = text.getBytes(StandardCharsets.UTF_8); Path tmp = dst.resolveSibling(dst.getFileName() + ".tmp"); Files.write(tmp, out, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE); Files.move(tmp, dst, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE); // 4) 回读校验：重新用严格 UTF-8 解码，比对字符序列 String back = StandardCharsets.UTF_8.newDecoder() .onMalformedInput(CodingErrorAction.REPORT) .decode(ByteBuffer.wrap(Files.readAllBytes(dst))) .toString(); if (!back.equals(text)) { throw new IllegalStateException("回读校验失败: " + src); } return text.length(); } }

第 1 步用REPORT而不是默认的REPLACE，是这道流程的守门人。如果检测阶段把编码判错了，比如把 GBK 误判成 UTF-8，这里的严格解码会立刻抛异常，转换中止，而不是安静地生成一个满是U+FFFD的文件。这是「宁可失败也不产出坏数据」的原则，批量任务里尤其重要。

第 3 步走临时文件加ATOMIC_MOVE，是为了防止转换中途进程被杀导致目标文件变成半截。在同一个文件系统内ATOMIC_MOVE是原子操作，要么旧文件还在，要么新文件完整，不存在中间态。

第 4 步的回读校验看着像多余——刚写出去的内容再读一遍当然一样。但它防的是另一类问题：磁盘写入异常、编码器在边界情况下的行为差异、以及text.getBytes和decode之间的不对称。成本是一次额外的读 IO，换来的是「转换结果 100% 可信」这个结论，值。

批量执行时还要注意两件事。一是先做全量备份，别在原目录上直接覆盖，输出到一个平行的utf8/目录，确认无误后再整体替换。二是保留源文件的行尾风格，从 3.3 节的lineEnding列读出来，如果是CRLF就按CRLF写回，避免制造无意义的 diff。这两条都不难实现，但漏掉任何一条，代码审查时都会被追问。

5.2 用带标签语料算准确率：混淆矩阵与误判清单

检测器的准确率不能靠「我试了几个文件感觉挺准」来判断。可行的做法是准备一份带人工标签的语料，跑一遍批量检测，把结果和标签对齐成混淆矩阵。语料不需要很大，200 到 500 个文件就足以暴露系统性问题，关键是覆盖这几类：

跑完之后统计四类结果：正确判定、判成 UNKNOWN、判成错误编码、置信度低于阈值但编码正确。第四类不算错误，但比例高说明阈值设得太严，需要调--min-confidence。真正要盯的是第三类——判错比不判危险得多，因为下游会按错误编码去转换，产出看起来正常但内容已损的文件。

// 混淆矩阵核心逻辑，labels 是人工标签 Map<Path, String> Map<String, Map<String, Integer>> matrix = new TreeMap<>(); for (Map.Entry<Path, String> e : labels.entrySet()) { Verdict v = new FileChecker(1 << 20).check(e.getKey()); String predicted = v.charset() == null ? "UNKNOWN" : v.charset().name(); matrix.computeIfAbsent(e.getValue(), k -> new TreeMap<>()) .merge(predicted, 1, Integer::sum); } // 逐类算召回率：对角线 / 该行总和

跑完这份矩阵，通常会看到两个规律。第一，GBK 和 GB18030 之间的混淆最多，因为前者是后者的子集，只要判定顺序写对，这类混淆能压到接近零。第二，纯 ASCII 类的误判率取决于是否做了 4.1 节坑二里的短路处理，没做的话这一类的误判率能到三成以上，做了之后基本清零。把这两点修掉，整体准确率通常能上到 98% 以上，剩下的 2% 集中在极短文件（几十字节）和混合编码文件上，这两类本来就该由人工兜底，工具报UNKNOWN反而是正确的行为。

提示：混合编码文件（同一个文件里既有 GBK 段又有 UTF-8 段）在字节层面是不可能被正确分割的，任何检测器都只能给出多数投票的结果。这类文件的正确处置方式是在报告里标MIXED并阻断自动转换，交给人去手工拆分，别指望工具全自动搞定。

6. 给仓库加一道编码卡口：pre-commit 里的具体做法

检测器和转换器都跑顺之后，最后一个问题是怎么防止新代码把问题带回来。人工定期扫一遍不现实，最省事的位置是 Git 的pre-commit钩子——只检查本次暂存的文件，几秒钟出结果，不合规直接拦住提交。

钩子脚本本身很短，核心是把暂存文件列表传给 CLI：

#!/usr/bin/env bash # .git/hooks/pre-commit set -euo pipefail JAR="tools/encodingchecker.jar" TMP="$(mktemp -d)" trap 'rm -rf "$TMP"' EXIT # 1) 导出暂存区文件到临时目录，保持相对路径 git diff --cached --name-only --diff-filter=ACM \ | grep -Ei '\.(java|properties|xml|md|txt)$' \ | while IFS= read -r f; do mkdir -p "$TMP/$(dirname "$f")" git show ":$f" > "$TMP/$f" done || true # 2) 只对这些文件做检测，阈值抬到 0.9 if ! java -jar "$JAR" scan \ --path "$TMP" \ --min-confidence 0.9 \ --report "$TMP/report.csv"; then echo "编码检查未通过，明细如下：" column -s, -t < "$TMP/report.csv" | grep -v ',1.00,' echo "确认无误可用 git commit --no-verify 跳过，但请先修文件。" exit 1 fi

脚本里有两个细节值得说。一是用git show ":$f"而不是直接读工作区文件——暂存区的内容可能和工作区不一致（比如git add -p只暂存了部分改动），检查暂存区才是对的。二是把阈值抬到 0.9，比日常扫描的 0.8 更严，因为提交是入口，宁可多拦几个让人确认，也别让一个 0.85 的文件混进历史。

钩子有个天然缺陷：它只装在本地，团队成员不装就等于没有。所以我一般会在仓库里同时放一份 CI 任务，用同样的命令扫全量，作为兜底。本地钩子负责快速反馈，CI 负责最终把关，两层加起来才算闭环。

这套东西跑起来之后，最明显的变化不是发现了多少问题，而是新人拉下代码后不再问「为什么我的 IDE 打开是乱码」。编码问题从「偶发玄学」变成了一条明确的、可执行的检查项。

从那以后我每次接新仓库，第一件事都是先跑一遍全量扫描，把报告里置信度低于 0.8 的那几十行挨个看一遍再动手改代码——这个习惯帮我省掉过至少两次「改了半天发现是文件编码不对」的返工。希望帮到你。

本文还有配套的精品资源，点击获取