Go filepath.WalkDir 遇到 fs.SkipDir 为什么有两种含义：目录跳过与遍历终止

给目录做扫描排除时，最容易误判的一行代码就是 return fs.SkipDir。它不是“永远跳过当前目录”这么简单：回调当前拿到的是目录，才会跳过这个目录；回调当前拿到的是文件，返回同一个值会让 WalkDir 跳过该文件所在父目录的剩余项。判断点只有一个：当前的 fs.DirEntry 到底是不是目录。

需要排除目录时，在目录分支返回 fs.SkipDir；需要跳过某个文件并继续扫描同级文件时，返回 nil，不要把文件分支也写成 fs.SkipDir。

同一返回值，为什么会走两条路径

filepath.WalkDir 实际使用的是 io/fs 的 WalkDirFunc。回调每次收到三个值：当前路径 path、目录项 d 和可能的访问错误 err。当 err 不为空时，应先决定是记录并继续，还是把错误返回给遍历器。

当 err == nil 时，d.IsDir() 才是这道题的分叉开关。目录节点返回 fs.SkipDir，遍历器不会进入它；普通文件节点返回 fs.SkipDir，语义则退化为“不要再访问当前父目录的其他项”。这也是它和“过滤掉一个文件”之间的差别。

先写一个能看出访问顺序的例子

下面的示例扫描 ./sample，想排除名为 .git 的目录，并忽略扩展名为 .tmp 的文件。关键是：排除目录和忽略文件不能共用同一个返回值。

package main

import (
    "fmt"
    "io/fs"
    "path/filepath"
    "strings"
)

func main() {
    err := filepath.WalkDir("./sample", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }

        if d.IsDir() && d.Name() == ".git" {
            return fs.SkipDir
        }
        if !d.IsDir() && strings.HasSuffix(d.Name(), ".tmp") {
            return nil
        }

        fmt.Println(path)
        return nil
    })
    if err != nil {
        panic(err)
    }
}

执行到 .git 时，回调返回 fs.SkipDir，因此不会再看到 .git/config 等后代路径。执行到 cache.tmp 时只是不打印它，随后同级的 main.go 仍会被访问。

文件分支误用 fs.SkipDir 会漏掉什么

把文件过滤改成 return fs.SkipDir，看起来像是“跳过这个文件”，实际会影响同级遍历。假设 sample 下依次有 a.tmp、b.go、c.go，回调在 a.tmp 返回 fs.SkipDir 后，后面的两个文件都不会再进入回调。

这条规则也解释了为什么它能用于“遇到某个目录就停止深入”：目录项本身是遍历分支的入口。文件项没有可深入的子树，所以遍历器只能把这个信号解释成“跳过父目录剩余内容”。

和 Walk 的差别，别只记住函数名

filepath.Walk 的回调拿到的是 os.FileInfo，WalkDir 拿到的是 fs.DirEntry。后者可以在进入目录前返回 fs.SkipDir，避免读取这个目录；它还明确支持 fs.SkipAll 表达“剩下的全部都不看”。

如果代码只需要排除目录，WalkDir 的回调条件更直观；如果项目依赖旧接口或必须使用 FileInfo 的完整元数据，再考虑保留 Walk。不要因为名字相似，就把两个回调的参数和跳过语义混写。

最后用三个检查点收住边界

第一，先处理 err，不能在 d 可能为空时直接调用 d.IsDir()。第二，目录排除条件必须放在目录判断之后，并返回 fs.SkipDir。第三，文件过滤只返回 nil，除非你的真实意图是连同父目录的剩余兄弟项一起停止。

如果需要“发现一个特殊文件后结束整个扫描”，用 fs.SkipAll 表达意图更准确；如果是权限错误、磁盘错误等异常，则把原始错误返回，让调用方知道扫描没有完整完成。

相关问答

fs.SkipDir 会跳过根目录吗？

会。若回调在根目录节点返回它，根目录下的遍历不会继续，整个调用通常以 nil 结束。

忽略一个文件最安全的返回值是什么？

通常是 nil，并且不要打印或收集该文件；这样只跳过当前文件，兄弟项仍会继续。

什么时候使用 fs.SkipAll？

当某个条件意味着剩余文件全部没有必要访问时使用，例如扫描已达到业务上限；它表达的是全局停止，不是目录级排除。

小结

fs.SkipDir 的含义依赖回调当前看到的节点类型。把 d.IsDir() 当作分支开关，再分别处理目录排除、文件过滤和全局终止，目录扫描的访问范围就能被准确控制。