WalkDir 遇到错误时返回、忽略还是跳过目录应如何决定

使用 fs.WalkDir 扫描目录时，遇到错误不要先问“要不要忽略”，而要先问“这部分结果缺失后，业务还能不能接受”。索引、备份清单等要求完整性的任务通常返回错误；统计、清理、候选文件扫描可以记录错误后继续；明确不关心的目录则返回 fs.SkipDir。只有整个结果已经失去意义时，才返回 fs.SkipAll。

一、先理解 WalkDir 回调里的错误位置

WalkDir 会从 root 开始调用回调，根节点本身也会被访问。官方约定是，遍历文件或目录时出现的错误交给 WalkDirFunc 处理；如果目录内容读取失败，回调收到的 err 可能对应当前路径，而 d 不一定可用。因此回调第一行应当是错误分支，而不是直接调用 d.IsDir()。

另外，WalkDir 按词法序遍历目录，需要先读取整个目录再继续，这让输出稳定但不等于“实时目录快照”。它默认不跟随目录中的符号链接；根路径本身如果是符号链接，则会遍历其目标。错误策略不能脱离这些边界单独设计。

二、用三种返回值表达三种策略

把返回值理解成遍历范围控制，会比把所有错误都当成普通日志更准确。下面的表格可以作为选择清单：

这里有一个容易混淆的点：fs.SkipDir 不是“忽略当前错误”的同义词，它表达的是目录范围控制。如果当前回调对应普通文件，返回它并不会产生同样的语义；对文件错误通常应返回错误、记录后返回 nil，或由业务自行决定是否停止。

三、把策略写成可维护的回调

下面的示例把严格模式和容错模式放在同一个函数中。示例只展示策略，不把本机执行结果伪装成证据；生产代码可以将 failures 写入日志或返回给上层。

package main

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

func scan(root string, strict bool) ([]string, []string, error) {
    var files []string
    var failures []string
    ignored := map[string]bool{".git": true, "node_modules": true}

    // DirFS 让回调使用 fs.FS 的相对路径，便于统一处理不同来源的文件系统。
    err := fs.WalkDir(os.DirFS(root), ".", func(name string, d fs.DirEntry, err error) error {
        // 目录读取失败时 d 可能为 nil，必须先判断 err 再访问 d。
        if err != nil {
            failures = append(failures, fmt.Sprintf("%s: %v", name, err))
            if strict {
                // 索引和备份需要完整结果，任何关键错误都交给调用方。
                return fmt.Errorf("遍历 %s 失败: %w", name, err)
            }
            // 容错扫描保留失败清单，并继续访问其他可读条目。
            return nil
        }

        if d.IsDir() && ignored[path.Base(name)] {
            // 只跳过当前目录及子树，不影响其他兄弟目录。
            return fs.SkipDir
        }
        if !d.IsDir() {
            // 这里只收集普通遍历结果，读取文件内容可放在后续阶段。
            files = append(files, name)
        }
        return nil
    })
    return files, failures, err
}

func main() {
    // 调用方应根据业务选择 strict，而不是把所有错误静默吞掉。
    files, failures, err := scan("./data", false)
    fmt.Println(files, failures, err)
}

如果要识别权限问题，可以在错误分支中使用 errors.Is(err, fs.ErrPermission)；不要只比较错误字符串。严格模式下保留 %w 包装，便于上层继续使用 errors.Is 或 errors.As 判断根因。忽略目录的判断应基于当前目录名或明确的相对路径集合，不要用模糊的字符串前缀误伤同名目录。

四、用业务目标检查结果完整性

调用方至少要同时拿到三类信息：成功收集的文件、失败路径、WalkDir 自身返回的错误。只返回文件列表会把“权限不足导致没扫描到”和“目录本来就没有匹配文件”混在一起。

• 需要完整快照：返回第一个无法接受的错误，重试或修复权限后再生成结果。
• 允许部分成功：继续遍历，但将失败路径计数、记录原因，并在结果状态中标注不完整。
• 主动排除目录：仅对确定不参与业务结果的目录使用 fs.SkipDir。
• 根前置条件失效：例如配置的根不存在或关键文件系统不可访问，可用 fs.SkipAll 结束当前遍历。

还要记住，WalkDir 不会跟随目录内符号链接。若业务需要遍历链接目标，不能靠改变错误返回值实现，而要重新设计文件系统访问方式，并评估循环链接和越界访问风险。

相关问题

回调里的 d 为 nil 时应该怎么写？

先处理 err 并使用 path 记录失败位置；只有确认 err == nil 后，才调用 d.IsDir() 等方法。

跳过一个文件应该返回 fs.SkipDir 吗？

不应该把它当成通用的“跳过当前项”。对普通文件，通常记录后返回 nil，或直接返回业务错误；fs.SkipDir 主要用于跳过目录子树。

return nil 会让 WalkDir 忽略所有后续错误吗？

不会。它只处理当前一次回调；后续错误仍会再次进入回调，所以容错模式应持续记录失败路径。