Go fs.WalkDir 怎样跳过目录而不读取其全部内容

在项目扫描、构建缓存或生成工具中，常见的性能问题不是“不会遍历”，而是把不相关的大目录也完整读了一遍。fs.WalkDir 的关键点是：它会先调用 WalkDirFunc，再决定是否读取当前目录。因此只要在目录第一次进入回调时返回 fs.SkipDir，当前目录的子树就不会继续展开。

跳过一个目录用 fs.SkipDir，停止剩余所有遍历用 fs.SkipAll；真正的访问错误不要伪装成跳过，应该按业务决定是否返回错误。

• d.IsDir() 用来确认当前路径是不是目录，目录判断要放在读取动作之前。
• 返回 fs.SkipDir 会跳过当前目录及其子树，但兄弟目录仍会继续。
• 返回 fs.SkipAll 会跳过后续所有文件和目录，并让遍历正常结束。
• 回调收到非空 err 时，通常说明该路径无法正常访问，直接返回错误可以避免漏扫。

为什么回调能在读取目录前剪枝

WalkDir 的回调签名是 func(path string, d fs.DirEntry, err error) error。官方文档特别说明，目录读取之前会先调用一次回调；这次调用给了程序返回 SkipDir 或 SkipAll 的机会。也就是说，剪枝并不是读完目录列表后再过滤文件，而是在目录展开前阻止下一步。

这一区别对大目录很重要。比如扫描项目源码时，.git、生成物目录或缓存目录可能包含大量层级。回调只需看当前目录名，就能让遍历器不再进入该目录。需要注意的是，WalkDir 为了保证词法顺序，会在继续遍历某个目录前读取完整目录列表；所以越早返回 SkipDir，越能避免这次目录读取和后续子树访问。

最小写法：目录命中规则就返回 SkipDir

下面的示例只跳过名为 .git、node_modules 和 dist 的目录，普通文件仍然交给后续处理。示例把错误判断放在最前面，避免在 d 可能为 nil 时调用方法。

package main

import (
    "fmt"
    "io/fs"
    "log"
    "os"
    "path"
)

func main() {
    root := os.DirFS(".")
    skip := map[string]bool{
        ".git":         true,
        "node_modules": true,
        "dist":         true,
    }

    err := fs.WalkDir(root, ".", func(name string, d fs.DirEntry, err error) error {
        // 目录打不开时先把真实错误交给调用方，不把漏扫伪装成成功。
        if err != nil {
            return err
        }
        // 当前回调发生在读取目录之前，命中规则即可剪掉整棵子树。
        if d.IsDir() && skip[path.Base(name)] {
            return fs.SkipDir
        }
        // 这里可以处理文件；目录只作为遍历边界，不读取文件内容。
        if !d.IsDir() {
            fmt.Println(name)
        }
        return nil
    })
    if err != nil {
        log.Fatal(err)
    }
}

这里的 path.Base 只取当前路径的最后一段，适合按目录名做剪枝。返回 fs.SkipDir 后，WalkDir 不会再访问该目录的子项；遍历仍会回到上层并继续处理其他兄弟路径。

SkipDir 和 SkipAll 到底差在哪里

两者都不是普通错误，而是 WalkDirFunc 识别的控制信号。区别在影响范围：

找到目标后怎样停止剩余遍历

如果任务是查找第一个满足条件的文件，继续扫完整棵树就没有必要。此时可以在命中目标后返回 fs.SkipAll，并在外层根据一个变量判断是否已经找到。

var found string

err := fs.WalkDir(root, ".", func(name string, d fs.DirEntry, err error) error {
    // 回调错误优先传播，避免把权限问题误判为“没有找到”。
    if err != nil {
        return err
    }
    if !d.IsDir() && d.Name() == "config.yaml" {
        // 找到目标后停止整棵树的剩余遍历，而不是只跳过当前目录。
        found = name
        return fs.SkipAll
    }
    return nil
})
if err != nil {
    log.Fatal(err)
}
if found == "" {
    fmt.Println("未找到目标文件")
} else {
    fmt.Println("找到：", found)
}

SkipAll 的意义是“遍历已经完成”，不是错误。若业务上还需要区分“找到目标”和“遍历完整棵树后没找到”，可以像示例一样用 found 保存命中结果，而不要只根据 WalkDir 的返回值判断。

err 非 nil 时为什么不能直接调用 d.IsDir

当根目录的初始 Stat 失败时，回调可能收到 d == nil；当目录的 ReadDir 失败时，回调会带着目录项再次报告错误。两种情况下都应该先检查 err，再访问 d。如果确实允许跳过某类访问失败，也要明确记录规则，否则扫描结果会把“无法读取”混成“目录不存在”。

err := fs.WalkDir(root, ".", func(name string, d fs.DirEntry, err error) error {
    // 根目录 Stat 失败时 d 可能为空，先处理错误是安全前提。
    if err != nil {
        return fmt.Errorf("访问 %s 失败: %w", name, err)
    }
    // 只有 err 为空时，才读取 DirEntry 的目录属性。
    if d.IsDir() && d.Name() == "private-cache" {
        return fs.SkipDir
    }
    return nil
})

这里用 %w 包装错误，是为了保留底层错误，调用方仍可用 errors.Is 或 errors.As 做分类处理。文章的范围只涉及遍历控制，不把错误包装方式延伸成新的重试策略。

一眼判断剪枝是否写对

1. 先看 err：非空时不要调用 d.IsDir、d.Name。
2. 只想排除一个目录时，条件必须包含 d.IsDir()，然后返回 fs.SkipDir。
3. 找到全局目标后才使用 fs.SkipAll，否则会把尚未扫描的兄弟目录一起跳过。
4. 不要把 fs.SkipDir 当成“跳过当前文件”；对非目录返回它会影响父目录。
5. 不要根据 WalkDir 返回 nil 就推断所有路径都成功访问过，回调如何处理错误决定了结果含义。

常见问题

返回 fs.SkipDir 会不会跳过同级目录？

不会。它针对当前目录及其子树；遍历回到父目录后，仍会继续处理其他兄弟项。

fs.SkipAll 返回后 WalkDir 是错误吗？

不是。它是官方定义的正常控制信号，表示后续遍历不需要继续，通常返回 nil。

为什么目录已经判断了，还是发生了 ReadDir？

常见原因是返回值写成了 nil，或者剪枝条件只判断了路径字符串却没有命中实际目录名。目录的第一次回调必须直接返回 fs.SkipDir。

可以忽略所有 err 让扫描继续吗？

可以按业务把某些可接受的错误记录后跳过，但不应无条件吞掉错误。权限或 I/O 失败若影响扫描完整性，应返回给调用方。

官方资料：https://pkg.go.dev/io/fs#WalkDirFunc