如何通过结合 Files.walkFileTree() 和 SimpleFileVisitor 构建定制化文件系统树遍历？

本文共计719个文字，预计阅读时间需要3分钟。

关键不在于遍历树的本身，而在于SimpleFileVisitor子类中重写的那些几个回调方法——preVisitDirectory、visitFile、visitFileFailed和postVisitDirectory。它们按实际访问顺序被调用，每个方法的返回值决定是否继续遍历：

怎么跳过特定目录或文件（比如 .git 或 class 文件）

不能靠路径字符串匹配后 return，必须在对应回调里返回 SKIP_SUBTREE 或 CONTINUE。常见错误是只过滤文件名却没处理目录，结果 .git 目录仍被递归进入。

• preVisitDirectory：检查 dir 的 getFileName()，如果是 ".git" 或 "target"，直接 return FileVisitResult.SKIP_SUBTREE
• visitFile：用 file.getFileName().toString().endsWith(".class") 判断，匹配则跳过处理，但别 return SKIP_SUBTREE（它对文件无效）
• 注意：路径比较要用 Objects.equals(dir.getFileName(), Path.of(".git"))，避免因大小写或符号链接导致漏判

如何安全捕获并处理权限不足或 I/O 错误

visitFileFailed 是唯一能拿到异常对象的地方，不重写它，AccessDeniedException 或 IOException 会直接中断整个遍历。它默认返回 CONTINUE，但你得显式处理。

• 如果只是想跳过无法读取的文件，return FileVisitResult.CONTINUE 即可
• 如果要记录错误，把 IOException 传入日志，再 return CONTINUE；不要 throw 新异常，否则遍历终止
• 特别注意 Windows 下的 java.nio.file.AccessDeniedException 常出现在 System Volume Information 目录，必须在这里吞掉

为什么 visitFile() 拿到的 Path 不是绝对路径，且可能和 walk 开始时的 base 不一致

因为 Files.walkFileTree() 默认以相对路径方式传递给 visitor 方法。如果你需要完整路径做后续操作（比如复制、删除），必须在构造 visitor 时把起始 Path 传进去，然后在 visitFile 里用 basePath.resolve(file) 拼接。

• 错误做法：file.toAbsolutePath() —— 它返回的是基于当前工作目录的绝对路径，不是原树根下的绝对路径
• 正确做法：在自定义 SimpleFileVisitor 构造器中接收 Path root，在 visitFile 中用 root.resolve(file)
• 性能提示：resolve() 是轻量操作，但频繁调用仍建议缓存 root 字段，而非每次重新 Paths.get(...)

实际最易忽略的是 visitFileFailed 的沉默失败行为——不重写它，某些系统目录报错就停了，你以为遍历完了，其实差了一半。