Java Files.mismatch 比较大文件的返回值

比较大文件时，Files.mismatch(path1, path2) 返回的是首个不一致字节的从 0 开始的偏移量，返回类型是 long。两个文件完全一致时返回 -1L；如果较短文件的全部内容都与较长文件前缀相同，则返回较短文件的字节数。也就是说，返回值不是“差了多少字节”，也不是文本字符下标。

官方文档：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/Files.html

处理结果时先判断 -1L，再把非负值解释为字节偏移；大文件比较必须用 long 接收，长度不同时还要区分“前缀相同”和“中途出现差异”。

Files.mismatch 的返回值怎样分类

可以把返回值直接映射为四种情况。-1L 表示两个路径定位到同一个文件，或两个文件大小相同且每个对应字节都相同。0L 表示第一个字节就不同。正数表示从文件开头数起的首个不同字节位置，偏移从 0 开始。

还有一个容易漏掉的情况：两个文件长度不同，但较短文件的所有字节都与较长文件的开头一致。这时没有“较短文件中的不一致字节”，方法会返回较短文件的大小。例如短文件是 4,096 字节、长文件以前 4,096 字节完全相同，返回值就是 4096L。

为什么比较大文件要用 long

方法签名返回 long，因为文件偏移按字节计算，不能用 int 表示所有大文件位置。返回值的上界与较小文件的大小有关，因此不要把结果强制转换成整数，也不要把它当成字符位置。

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

public class FileCompare {
    public static long firstMismatch(Path left, Path right) throws IOException {
        // 返回值是字节偏移；-1L 代表完全匹配，必须保留 long 类型。
        return Files.mismatch(left, right);
    }

    public static String describe(Path left, Path right) throws IOException {
        // 先取得文件大小，用于解释“较短文件是公共前缀”的情况。
        long mismatch = Files.mismatch(left, right);
        long leftSize = Files.size(left);
        long rightSize = Files.size(right);

        if (mismatch == -1L) {
            // 相同文件内容或同一路径不会产生差异位置。
            return "文件内容一致";
        }
        if (mismatch == Math.min(leftSize, rightSize)
                && leftSize != rightSize) {
            // 短文件已经全部匹配，差异来自长度不同，而非某个已有字节。
            return "较短文件是公共前缀，长度差异从字节 " + mismatch + " 开始";
        }
        // 非负值表示首个不一致字节的 0 起始位置。
        return "首个不一致字节偏移：" + mismatch;
    }
}

这里的判断只是在解释返回值，不会把整个文件读入内存。对很大的文件，仍应保留 long，并在业务日志或数据库字段中使用能容纳 64 位整数的类型。

长度不同和文本文件，应该怎样理解偏移

Files.mismatch 比较的是文件内容中的字节。即使文件保存的是 UTF-8 文本，返回值也不是第几个汉字或第几个 Unicode 码点。一个汉字可能对应多个字节，返回的偏移可能落在一个字符的中间。

如果两个文件只有末尾多出内容，返回较短文件长度；如果在公共前缀之内出现差异，则返回那个差异字节的下标。下面的关系可以帮助区分“内容差异”和“长度差异”：先比较共同范围，较短文件耗尽后，剩余部分只能表现为长度差异。

大文件比较时的异常和边界

方法声明抛出 IOException，路径不存在、没有读取权限或底层文件系统读取失败时，调用方应保留异常上下文，不要把异常误判为“文件不一致”。如果文件在比较期间被其他进程修改，结果可能无法代表某一个稳定时刻；官方 API 也没有承诺这个比较相对于其他文件系统操作是原子的。

try {
    // 这里把读取失败和“内容不同”分开记录，便于后续重试或告警。
    long offset = Files.mismatch(source, backup);
    if (offset == -1L) {
        System.out.println("内容一致");
    } else {
        System.out.println("首个差异字节：" + offset);
    }
} catch (IOException e) {
    // I/O 失败不是比较结论，记录路径后交给上层决定是否重试。
    throw new IllegalStateException("无法读取待比较文件", e);
}

落地时可以按这份清单检查：返回值用 long；-1L 单独判断；非负值按字节偏移解释；长度不同且偏移等于较短文件大小时标记为公共前缀；文本场景不要把字节下标直接当字符下标；对 IOException 单独处理。

常见问题

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

表示两个文件的第 0 个字节已经不同，也就是从文件开头就出现差异。

返回值等于较短文件大小时一定是完全不同吗？

不一定。若文件长度不同且较短文件是较长文件的完整前缀，这个返回值表示长度差异；只有结合两个文件大小，才能正确解释。

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

不能，它接收两个 Path 并比较文件字节。字符串应先明确编码转换为文件或字节数组，再根据需求选择其他比较方式。