Go io/fs 跨目录扫描怎么处理：WalkDir、权限错误与主动中断

给目录做索引、清理临时文件或统计代码行数时，最容易出问题的不是“怎么递归”，而是递归遇到权限错误后到底要不要继续。Go 的 io/fs 把文件系统访问抽象成了接口，配合 fs.WalkDir 可以跨目录扫描；但它不会替你决定哪些错误可忽略、哪个目录该跳过，也不会自动响应业务取消。

先把扫描器的边界说清楚

这个小项目只做三件事：从一个 fs.FS 根开始遍历，收集普通文件的相对路径，遇到不可读目录时记录错误并继续。调用方还可以通过上下文取消扫描。它不解析符号链接目标，也不把权限问题伪装成“没有文件”。

把结果拆成“文件列表”和“错误列表”很重要。只返回一个 []string，调用方无法区分“目录真的为空”和“扫描到一半读不了”；只返回第一个错误，又会让批量索引因为一个坏目录全部失败。

WalkDir 回调里的路径和错误分别代表什么

fs.WalkDir(fsys, root, fn) 会把 root 作为遍历起点。回调的 path 使用斜杠分隔，并且相对于传入的文件系统根；如果使用 os.DirFS("/srv/app")，回调收到的可能是 cache/a.tmp，而不是操作系统绝对路径。

回调签名中的 err 不能直接忽略：

func(path string, d fs.DirEntry, err error) error

当目录项本身已经读不到时，d 可能是 nil。先判断错误，再访问 d.IsDir()，否则一个权限问题就可能变成空指针崩溃。

做一个可取消、可解释的目录扫描器

下面的实现故意不把所有错误都当成致命错误。它保留扫描数量和错误路径，调用方可以在最后决定是告警、重试还是拒绝这批索引。

package scanner

import (
    "context"
    "io/fs"
)

type Result struct {
    Files  []string
    Errors []PathError
}

type PathError struct {
    Path string
    Err  error
}

func Scan(ctx context.Context, fileSystem fs.FS, root string) (Result, error) {
    var result Result
    walkErr := fs.WalkDir(fileSystem, root, func(path string, d fs.DirEntry, err error) error {
        if ctx.Err() != nil {
            return ctx.Err()
        }
        if err != nil {
            result.Errors = append(result.Errors, PathError{Path: path, Err: err})
            if d == nil {
                return nil
            }
        }
        if d == nil {
            return nil
        }
        if d.IsDir() {
            if d.Name() == ".git" || d.Name() == "node_modules" {
                return fs.SkipDir
            }
            return nil
        }
        result.Files = append(result.Files, path)
        return nil
    })
    if walkErr != nil {
        return result, walkErr
    }
    return result, nil
}

这里有三个值得保留的细节。第一，取消检查放在回调最前面，避免继续处理已经排队的文件。第二，fs.SkipDir 只对目录名生效；如果把它用于普通文件，语义很容易被误读。第三，权限错误被写入 Errors 后返回 nil，所以结果必须带着“部分成功”的信息向上游传递。

用 os.DirFS 和 fstest.MapFS 验证两类场景

真实扫描可以从 os.DirFS 开始，它把绝对目录封装成一个根。测试则更适合用 testing/fstest.MapFS 构造稳定的小文件树，避免测试依赖开发机上的目录结构。

ctx := context.Background()
fileSystem := os.DirFS("/srv/app")
result, err := scanner.Scan(ctx, fileSystem, ".")
if err != nil {
    return fmt.Errorf("scan app files: %w", err)
}
log.Printf("files=%d errors=%d", len(result.Files), len(result.Errors))

如果入口是 fstest.MapFS，文件名同样要遵守 io/fs 的相对路径规则，例如 config/app.yaml，不要把 /tmp/config 直接传给 WalkDir。入口参数错误属于整次扫描都无法成立的错误，不应混进单个路径的可恢复错误。

权限错误、跳过目录和主动停止怎么选

可以按下面的判断处理，不要看到任何错误都重试：

• 某个文件读不了，但其他目录仍有价值：记录路径和错误，返回 nil。
• 某个目录属于明确的排除范围：确认 d.IsDir() 后返回 fs.SkipDir。
• 上下文已取消：返回 ctx.Err()，让上层知道这是取消而不是扫描成功。
• 入口不存在、根路径非法或文件系统实现返回结构性错误：直接返回错误。

生产代码里还应避免把 permission denied 的文本作为唯一判断依据。错误可能被包装，应该使用 errors.Is 检查 fs.ErrPermission，同时把原始错误保留在日志或结果对象里。

常见问题

WalkDir 能不能直接拿到绝对路径？

不能直接拿到。它返回的是相对于 fs.FS 根的路径；如果确实需要绝对路径，应由调用方保存根目录并使用安全的路径拼接，而不是把回调路径当成绝对路径。

遇到权限错误时返回 nil 会不会隐藏故障？

只有在同步记录错误的前提下才适合返回 nil。结果对象要保留错误数量和具体路径，并在索引、备份等业务层决定是否允许部分成功。

为什么不在循环外统一检查 context？

WalkDir 自己控制遍历循环，外层无法及时打断它。把检查放进回调，才能在每个目录项之间观察取消信号。

fs.SkipDir 和 context.Canceled 应该怎么区分？

fs.SkipDir 是局部控制流，只跳过一个目录；context.Canceled 是整次任务的终止原因，应由 WalkDir 返回给调用方。

把扫描结果交给后续任务

一个稳妥的调用链通常是“扫描—记录—决策”：先保存文件列表和路径错误，再由索引任务决定是否接受部分结果。这样既不会因为一个坏目录放弃整个批次，也不会把不完整的文件集误报为完整快照。真正上线前，用一个包含不可读目录、排除目录和取消信号的测试夹具跑一次，日志里能同时看到文件数、错误路径和取消原因，才算验收完成。