Go fs.SkipAll 和 SkipDir 在文件节点上有什么区别

我第一次在 fs.WalkDir 里“忽略一个文件”时，顺手返回了 fs.SkipDir。结果不是只忽略当前文件，而是同一目录后面的文件也没有再访问。这个行为看着反直觉，但官方定义非常明确。

直接结论：回调当前拿到的是文件节点时，返回 fs.SkipDir 会跳过这个文件所在父目录里尚未访问的条目；返回 fs.SkipAll 会停止整棵文件树的遍历，并把这次停止视为正常结束。若只是忽略当前文件，应返回 nil。

Go io/fs 官方文档：https://pkg.go.dev/io/fs

先记住结论：文件节点上的 SkipDir 会作用到父目录

图1：同一个返回值会因当前节点类型不同而改变控制边界，其中 SkipAll 始终停止整棵树。

为什么文件节点返回 SkipDir 会“多跳”一段

SkipDir 的名字容易让人只联想到目录，但 WalkDirFunc 的规则还考虑了当前节点不是目录的情况：如果 d.IsDir() 为假，所谓“当前目录”就解释为 path 的父目录。因此，它不是“忽略这个文件”的快捷写法，而是一种目录级剪枝信号。

WalkDir 按词法顺序访问目录项。假设某个目录中依次有 a.txt、b.tmp、c.txt，在 b.tmp 上返回 SkipDir 后，c.txt 不会再被访问。若只想排除 b.tmp，处理分支结束后返回 nil 即可。

err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, walkErr error) error {
    if walkErr != nil {
        // 真实访问错误不能伪装成正常剪枝
        return fmt.Errorf("walk %s: %w", path, walkErr)
    }

    if !d.IsDir() && strings.HasSuffix(path, ".tmp") {
        // 只忽略当前文件：返回 nil，继续访问同目录兄弟项
        return nil
    }
    return nil
})

攻击路径：把“忽略文件”误写成目录级控制

这里的风险通常不是外部攻击，而是控制边界被写大了。最常见的路径是：看到一个不关心的文件，返回 SkipDir，随后父目录剩余文件被静默跳过。备份、扫描、索引或规则检查任务因此得到不完整结果，却未必出现错误。

另一条路径是把 SkipAll 当作普通错误返回。它确实立即结束遍历，但 WalkDir 会把这个哨兵值消费掉并正常返回 nil。如果业务需要区分“找到目标后提前结束”和“遍历完整结束”，应在闭包外记录状态，而不是依赖最终错误。

风险分级：四种意图不要混用

• 低风险：只忽略当前文件，完成必要记录后返回 nil。
• 中风险：确认当前节点是目录后返回 fs.SkipDir，明确跳过整棵子树。
• 中高风险：在文件节点返回 fs.SkipDir，会扩大到父目录剩余条目，必须是刻意行为。
• 高影响控制：返回 fs.SkipAll，任何尚未访问的目录和文件都不会再进入回调。
• 真实失败：返回包装后的普通错误，让调用方收到失败原因。

防护控制：先写清意图，再选择返回值

图2：返回值应由控制意图决定；忽略单个文件应返回 nil，而不是 SkipDir。

package main

import (
    "fmt"
    "io/fs"
    "testing/fstest"
)

func main() {
    tree := fstest.MapFS{
        "cache/a.tmp":  {Data: []byte("a")},
        "cache/b.txt":  {Data: []byte("b")},
        "docs/readme.md": {Data: []byte("docs")},
        "stop.txt":     {Data: []byte("stop")},
    }

    foundStop := false
    err := fs.WalkDir(tree, ".", func(path string, d fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // 保留路径和原始错误，交给调用方处理
            return fmt.Errorf("walk %s: %w", path, walkErr)
        }

        if d.IsDir() && d.Name() == "cache" {
            // 当前是目录：只跳过 cache 子树
            return fs.SkipDir
        }
        if !d.IsDir() && d.Name() == "stop.txt" {
            // 当前是文件：停止整棵树，但不是失败
            foundStop = true
            return fs.SkipAll
        }
        return nil
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("提前找到停止标记:", foundStop)
}

这个例子把“剪掉一个目录”和“全局提前结束”拆成了两个条件。外部布尔值负责记录业务结果，返回值只负责控制遍历。

审计记录：err 参数必须先处理

WalkDirFunc 的第三个参数表示访问 path 时发生的问题。根节点初次 Stat 失败时，d 可能为 nil；目录读取失败时，回调还可能对同一路径再调用一次并携带错误。安全写法是在访问 d.IsDir() 或 d.Name() 前先判断 walkErr。

如果策略允许忽略某类权限错误，可以记录路径后返回 nil；如果不能接受不完整结果，就返回包装错误。不要在没有审计记录的情况下统一吞掉错误，否则“正常剪枝”和“访问失败”会混在一起。

验证清单：用最小目录树覆盖边界

• 文件节点返回 nil 后，同目录后续文件仍被访问。
• 文件节点返回 fs.SkipDir 后，同目录后续文件不再访问，但其他目录仍可能继续。
• 目录节点返回 fs.SkipDir 后，其子孙节点不进入回调。
• 任意节点返回 fs.SkipAll 后，不再有后续回调，且 WalkDir 返回 nil。
• 返回自定义错误后，WalkDir 返回可用 errors.Is 或 errors.As 检查的错误链。
• 回调收到非 nil 的 walkErr 时，不会先解引用可能为 nil 的 d。

常见问题

只想跳过一个文件，可以返回 SkipDir 吗？

不可以。返回 nil 表示当前文件处理完毕并继续；在文件节点返回 SkipDir 会跳过父目录中剩余条目。

SkipAll 会作为错误返回吗？

不会。它是控制遍历的特殊值，WalkDir 收到后停止剩余遍历并正常返回。需要知道为何提前结束时，请额外记录业务状态。

什么时候应该返回普通错误？

当结果不能接受缺失、权限问题、解析失败或业务校验失败时，返回带上下文的普通错误；这与主动剪枝的 SkipDir、SkipAll 是两类语义。

最后归纳：SkipDir 的边界取决于当前节点类型；在目录上是“跳过这棵子树”，在文件上是“跳过父目录余项”。SkipAll 不看节点类型，始终停止整个遍历。若只是忽略当前文件，返回 nil。