Go filepath.WalkDir 怎样读取受限根目录中的文件

filepath.WalkDir 负责按本地路径遍历目录，不提供“把所有访问绑定到 os.Root”的参数。若“受限根目录”要求遍历和文件读取都使用同一访问边界，适合先用 os.OpenRoot 打开目录，再用 fs.WalkDir(root.FS(), ".", 回调) 遍历，回调中继续通过这个 fs.FS 打开文件。不要在回调里改回 os.Open 拼接后的路径。

本文从 filepath.WalkDir 的使用需求出发，给出适用于 Go 1.24 及以上的小型扫描器：遍历普通文件，有限读取内容并计算摘要。示例限定 Linux、macOS 与 Windows 的本地目录，不将 Root 描述成完整进程沙箱。

Go 官方地址：https://go.dev/

先确定受限根目录的含义

常见目标有两种：一种只是“从指定目录开始遍历”，另一种还要求“后续打开文件不能因路径解析而访问目录树外的对象”。前者是遍历入口，后者需要把文件操作交给具有相应约束的接口。

filepath.WalkDir 不跟随遍历中遇到的符号链接，但这不等于任意后续文件打开都受到保护。例如，回调取得名称后另行打开，期间目录内容可能变化；字符串看起来仍在某个前缀下，也不能替代打开时的路径约束。Go 官方关于 Root 的文章解释了先解析再打开的竞态问题。

本例的业务目标是扫描操作者选定的资料目录，不修改目录，不读取无限大小的正文，也不承诺拿到全目录同一时刻的快照。

把遍历与读取绑定到同一个文件系统

这里的点表示 fsys 的根。fs.WalkDir 的回调名称使用斜杠分隔，直接传给同一个 fsys 即可。filepath.WalkDir 则操作系统路径字符串，不能把 root 当作它的第一个参数；迁移时应更换遍历入口，而不是在原函数外套一层名称检查。

实现有限读取并关闭每份文件

以下 main.go 是完整原创示例。digestFile 接收 fs.FS，读完一份文件后就返回并关闭文件，不把 defer 积累到整个目录任务结束。读取上限选为 10 MiB，是示例业务政策，不是标准库限制。

package main

import (
    "crypto/sha256"
    "fmt"
    "io"
    "io/fs"
    "os"
    "runtime"
)

const maxBytes int64 = 10 * 1024 * 1024

func digestFile(fsys fs.FS, name string) (digest string, size int64, err error) {
    // 使用同一受限文件系统打开，不重新拼接外部目录路径。
    f, err := fsys.Open(name)
    if err != nil {
        return "", 0, err
    }
    defer func() {
        if e := f.Close(); e != nil && err == nil {
            digest = ""
            err = e
        }
    }()
    info, err := f.Stat()
    if err != nil {
        return "", 0, err
    }
    if !info.Mode().IsRegular() {
        return "", 0, fmt.Errorf("打开后的对象不是普通文件")
    }
    // 多读一个字节识别超限，避免仅依赖可能变化的文件大小。
    h := sha256.New()
    size, err = io.Copy(h, io.LimitReader(f, maxBytes+1))
    if err != nil {
        return "", size, err
    }
    if size > maxBytes {
        return "", size, fmt.Errorf("内容超过单文件读取上限")
    }
    return fmt.Sprintf("%x", h.Sum(nil)), size, nil
}

func scan(base string) (err error) {
    // 本示例限定常用桌面与服务端平台，不对其他平台作相同承诺。
    switch runtime.GOOS {
    case "linux", "darwin", "windows":
    default:
        return fmt.Errorf("示例未支持当前平台 %s", runtime.GOOS)
    }
    root, err := os.OpenRoot(base)
    if err != nil {
        return fmt.Errorf("打开根目录: %w", err)
    }
    defer func() {
        if e := root.Close(); e != nil && err == nil {
            err = fmt.Errorf("关闭根目录: %w", e)
        }
    }()
    fsys := root.FS()
    return fs.WalkDir(fsys, ".", func(name string, d fs.DirEntry, walkErr error) error {
        // 访问失败时 d 可能为 nil，必须先处理错误。
        if walkErr != nil {
            return fmt.Errorf("遍历 %q: %w", name, walkErr)
        }
        if d.IsDir() {
            return nil
        }
        // 跳过遍历时看到的链接和其他非普通条目。
        if !d.Type().IsRegular() {
            return nil
        }
        digest, size, e := digestFile(fsys, name)
        if e != nil {
            return fmt.Errorf("读取 %q: %w", name, e)
        }
        // 只输出相对名称和摘要，内容不整份留在内存中。
        fmt.Printf("%q\t%d\t%s\n", name, size, digest)
        return nil
    })
}

func main() {
    if len(os.Args) != 2 || os.Args[1] == "" {
        fmt.Fprintln(os.Stderr, "用法: rootscan ROOT")
        os.Exit(2)
    }
    if err := scan(os.Args[1]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

文件内容以流式方式输入摘要对象。LimitReader 最多让复制器读取上限加一字节；如果多出的字节存在，就将该文件当作超限而结束任务。没有读取完的文件不输出成功摘要。即便事先查过大小，也保留实际读取上限，因为文件大小可能变化。

回调中的条目类型判断用来跳过观察到的链接和特殊条目，打开后又检查一次对象类型。它不是“所有时刻都禁止符号链接”的承诺；Root 可以解析未越出根目录的符号链接。如果业务要求完全禁止链接或应对恶意特殊文件，需要另行设计更严格的文件操作政策。

自行准备一个用于扫描的资料目录后，可将目录路径作为唯一参数传入：

# 使用包含 os.Root API 的 Go 版本运行；目录内容由操作者准备。
go run main.go ./materials

程序每成功处理一份文件，输出相对名称、实际读取字节数和 SHA-256 摘要。本文未执行示例，不预设目录中有哪些文件，也不提供伪造运行日志。

按阶段判断结果和错误

推荐先明确目标目录与业务文件规模，再建立 Root，最后让遍历和读取依赖同一 fsys。每个阶段的检查点都围绕实际操作结果，不围绕字符串前缀猜测。

根目录打不开时，没有后续遍历结果。回调收到 walkErr 时，应先处理它再访问 d；代码采用遇错停止，避免把不完整扫描误报为全部成功。若业务需要尽可能收集结果，可以单独记录错误并继续，但输出中必须明确哪些条目未处理。

单文件打开、查询类型、内容读取或关闭失败，都会使当前任务返回错误。已经输出的早先文件记录不会自动撤回。因此调用程序若要生成一份正式清单，应先写入临时结果，再在整个任务成功后确认成品；不能仅看见若干输出行就判断扫描完成。

退出码 0 表示本次遍历未返回错误，1 表示扫描失败，2 表示命令参数不正确。一次成功扫描也不保证后续再次读取时内容不变。

保留资源与平台边界

Root 的路径约束不等于内容不可变化，也不隔离挂载点或替代操作系统权限。硬链接、挂载目录和特殊对象等情况仍需结合目录的来源管理。本例面向资料目录，不用于扫描恶意参与者持续改写的设备节点或其他特殊文件树；字节上限也不能保证读取一定在某个时间内返回。

平台行为必须看当前文档。特别是 GOOS=js 的 Root 存在符号链接检查竞态限制，不能直接把本例的使用范围扩大过去；代码因此只接受列出的三个平台。WASI 与 Plan 9 也没有被纳入这个示例的支持范围。

目录遍历通常按字典序处理条目，这需要先读取一个目录的条目列表。限制单文件读取量并不同时限制目录条目数、目录深度或整个任务总耗时。大规模任务还应在业务层设置总量和调度策略。

常见问题

必须放弃 filepath.WalkDir 吗？普通可信本地目录遍历仍可以使用它；本文严格根目录访问目标选择 fs.WalkDir，是因为该接口能直接接收受限文件系统视图。

Root.FS 与 os.DirFS 可以随意替换吗？不能把二者的访问约束视为相同。若业务依赖 Root 的边界，替换成目录路径视图会改变这项设计。

跳过符号链接是否意味着绝无路径竞态？不是。跳过的是遍历时观察到的条目，实际打开仍必须沿用具有所需约束的接口。

扫描成功能当作文件快照吗？不能。Root 约束访问位置，不把目录中所有文件冻结在同一时刻。

官方资料：https://pkg.go.dev/path/filepath#WalkDir（本地遍历接口）；https://pkg.go.dev/io/fs#WalkDir（文件系统遍历接口）；https://pkg.go.dev/os#Root（Root 及平台限制）；https://go.dev/blog/osroot（受限文件操作的设计与注意事项）。