Java Files.mismatch 返回 -1 时如何解释

Files.mismatch(path1, path2) 返回 -1L 时，含义是两个路径对应的文件没有发现字节差异；它不是“比较失败”、不是“找不到差异位置”，也不是异常码。只要返回值是非负数，就把它当作从 0 开始计算的首个差异字节偏移；如果较短文件的全部字节都匹配，返回值还可能正好等于较短文件的字节长度，表示差异发生在 EOF 边界。

官方 API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/nio/file/Files.html

先把返回值分成三种情况

这个方法的签名是 public static long mismatch(Path path, Path path2) throws IOException，从 Java 12 开始提供。它比较的是文件内容的字节，而不是按文本编码解析后的字符。返回值可以先按下面的表理解：

返回 -1L 不只对应“两个文件路径相同”

最容易误读的一点是把 -1L 理解成“两个 Path 对象相等”。实际上，两个不同路径只要定位到大小相同、逐字节一致的文件，也会返回 -1L。因此它表达的是“没有发现内容差异”，不是路径字符串或文件名比较结果。

例如，backup/config.json 和 release/config.json 即使来自不同目录，只要字节内容完全相同，比较结果仍然是 -1L。反过来，文件名相同也不代表内容相同，真正需要关注的是返回值是否为非负数。

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

public class CompareFiles {
    public static void main(String[] args) throws IOException {
        Path left = Path.of("backup/config.json");
        Path right = Path.of("release/config.json");

        // mismatch 返回 -1L 表示没有发现字节差异。
        long offset = Files.mismatch(left, right);
        if (offset == -1L) {
            System.out.println("文件内容一致");
        } else {
            // 非负值是从 0 开始计算的首个差异字节偏移。
            System.out.println("首个差异字节偏移: " + offset);
        }
    }
}

非负返回值怎样定位首个差异字节

返回值从 0 开始计数：返回 0 表示第一个字节就不同，返回 5 表示前五个字节相同、索引为 5 的字节首次不同。它是字节偏移，不应直接当成中文字符下标或 Java String 的字符位置。

例如两个 UTF-8 文件在第 10 个字节处开始不同，返回值就是 10L。如果前面的中文字符占用了多个字节，肉眼看到的“第几个字”与这个数字不会一一对应；若需要展示文本差异，还要在稳定的编码边界上做额外解析。

为什么相同前缀仍会返回偏移量

假设文件 A 有 5 个字节，文件 B 有 9 个字节，前 5 个字节完全一致。此时并不存在“某个已有字节不一样”，但 A 在偏移量 5 的位置结束，B 仍有剩余字节，所以方法返回 5L。这个值等于较短文件的字节长度，也就是较短文件的 EOF 位置。

如果两个文件在较短文件结束之前就出现不同字节，返回值则是那个首个不同字节的偏移量，而不是较短文件长度。判断时可以把两个分支放在同一张速查表里：

用一个小程序输出可读的比较结论

如果业务日志不能只打印一个数字，可以把返回值和文件大小组合起来。下面的示例假设比较期间文件不会被其他程序修改；官方文档明确说明该方法相对于其他文件系统操作不保证原子性。

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

public class MismatchExplainer {
    static String explain(Path left, Path right) throws IOException {
        // 先读取长度，用于把 EOF 边界与普通差异区分开。
        long leftSize = Files.size(left);
        long rightSize = Files.size(right);

        // 结果是 -1L、首个不同字节偏移，或较短文件的 EOF 位置。
        long offset = Files.mismatch(left, right);
        if (offset == -1L) {
            return "内容完全一致";
        }

        long shorterSize = Math.min(leftSize, rightSize);
        if (leftSize != rightSize && offset == shorterSize) {
            // 较短文件的全部字节都匹配，差异来自长度不同。
            return "前缀一致，差异位于较短文件 EOF，偏移=" + offset;
        }

        // 这里表示较短文件结束前已经找到首个不同字节。
        return "首个不同字节偏移=" + offset;
    }

    public static void main(String[] args) throws IOException {
        System.out.println(explain(Path.of("a.bin"), Path.of("b.bin")));
    }
}

这里必须使用 long 接收结果，因为方法返回类型就是 long，而文件偏移可能超过 int 范围。若文件可能在比较过程中被写入，长度读取和内容比较可能不属于同一个快照，应先固定输入文件，或把比较安排在文件不会变化的阶段。

几个容易混淆的边界

字符下标和字节偏移不是一回事

Files.mismatch 面向文件字节。文本文件的编码、换行符和 BOM 都会影响字节序列，所以不要拿返回值直接索引一个 Java 字符串。

返回 -1L 不是异常结果

文件不存在、没有读取权限或发生 I/O 问题时，方法会以 IOException 等异常路径结束；只有正常比较且没有发现差异时，才会返回 -1L。调用方应保留异常处理，不要把所有负数都当成“文件相同”。

返回 EOF 位置不代表某个文件已有一个不同字节

当短文件是长文件的完整前缀时，返回值只是较短文件结束的位置。这个位置可以理解为“长度差异开始的边界”，不是短文件中一个实际存在的字节索引。

小结

记住一条判断规则即可：Files.mismatch 返回 -1L，表示没有发现字节差异；返回非负值，表示首个差异位置，或者在短文件前缀完全匹配时表示短文件的 EOF 位置。把它与文件大小、字节编码和文件是否稳定这三个条件一起看，就不会再把 -1 当成错误码，也不会把 EOF 边界误判成普通字符差异。

相关问题

Files.mismatch 返回 0 是什么意思？

表示两个文件的第 0 个字节就不同，也就是比较到的第一个字节已经出现差异。

文件大小不同但返回 -1L 可能吗？

按该方法的文件匹配语义不可能。只要文件大小不同，就一定存在差异；常见的返回值是较短文件的字节长度，前提是较短文件的全部内容都匹配。

Files.mismatch 能比较两个字符串吗？

不能直接比较字符串。它接收两个 Path，如果要比较字符串，应先明确编码并决定是比较字符、编码后的字节，还是把内容落到临时文件再比较。