Java Files.walk 的深度参数为什么不影响当前目录

用 Java 的 Files.walk(start, maxDepth) 遍历目录时，最容易误解的是：maxDepth 控制的是从起始路径向下访问的目录层级，不是“要跳过起始目录的层级”。因此 maxDepth=0 仍会返回传入的 start，只是不会继续展开它的子项。要只拿当前目录里的文件，应该用合适的深度再配合筛选，而不是把深度写成 0。

Files.walk 的深度是从起始 Path 算起

可以把目录想成一棵树。假设 data 下面有 report.csv 和 2026/report.csv，传入的 data 自己就是第 0 层：

所以标题里的“当前目录不受影响”其实是一个层级定义问题。官方 API 明确说明返回流至少包含起始文件，深度为 0 时只访问起始文件；目录遍历仍然是惰性的、深度优先的。下面这段代码先用 maxDepth=1 拿到当前目录及其直接子项，再只保留普通文件：

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

public class DirectFiles {
    public static List listDirectFiles(Path root) throws IOException {
        // 深度 0 是 root，深度 1 才包含 root 的直接子项。
        try (var paths = Files.walk(root, 1)) {
            return paths
                    // 过滤条件只决定保留哪些 Path，不会改变遍历深度。
                    .filter(Files::isRegularFile)
                    .toList();
        }
    }
}

这里的关键不是把 maxDepth 改成 0，而是先让遍历抵达第一层，再用 Files::isRegularFile 排除目录。若 root 本身是普通文件，maxDepth=1 也只会得到它；深度参数不会把一个文件变成目录。

别把过滤条件和遍历深度混成一件事

实际项目通常还会限定后缀、文件名或目录类型。例如只扫描 data 下的 CSV 文件，可以把“走到哪一层”和“留下什么结果”拆开写。这样排查结果时，先看深度是否足够，再看过滤条件是否过严：

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

public class CsvScanner {
    public static List listCsv(Path root) throws IOException {
        // maxDepth=2 允许进入 root 的下一层目录，但不会无限下钻。
        try (var paths = Files.walk(root, 2)) {
            return paths
                    // 先确认是普通文件，再按业务后缀筛选。
                    .filter(Files::isRegularFile)
                    .filter(path -> path.getFileName().toString().endsWith(".csv"))
                    .toList();
        }
    }
}

Files.walk 默认不跟随符号链接；如果显式传入 FOLLOW_LINKS，还要留意循环链接带来的 FileSystemLoopException。另一个容易漏掉的边界是资源：流在消费期间可能持有一个或多个打开的目录，只有关闭流后目录才会释放。即使最终操作是 toList()，也不要省略 try。

什么时候改用 Files.find 或 walkFileTree

只需要按路径做简单筛选时，Files.walk 足够；如果筛选本身还要用文件属性，Files.find 能把 Path 和 BasicFileAttributes 一起交给匹配器，少做一次属性读取。需要在进入目录、访问文件、访问失败和离开目录时分别处理，才考虑 Files.walkFileTree。

如果遍历过程中出现访问目录失败，惰性流可能在终端操作时抛出 UncheckedIOException。生产代码可以在调用边界记录具体路径并决定跳过还是终止，但不要用捕获异常的方式掩盖资源未关闭问题。

相关问题

为什么 maxDepth=1 还会返回当前目录？

因为起始路径固定是深度 0，参数 1 表示在保留它的基础上再访问一层。

只要当前目录下的文件应该怎么写？

使用 Files.walk(root, 1)，再用 Files::isRegularFile 或后缀条件过滤。

Files.walk 返回的 Stream 一定要关闭吗？

要。它可能持有打开的目录，推荐始终放在 try-with-resources 中。