Go io/fs WalkDir 怎样同时遍历磁盘和嵌入资源

如果一个 Go 服务既要扫描磁盘上的模板，又要扫描通过 //go:embed 打进二进制的默认资源，不必为两种来源各写一套递归逻辑。os.DirFS 和 embed.FS 都实现了 io/fs.FS，因此可以把“资源来自哪里”留在装配层，把“怎样遍历、过滤和处理”收敛到一个 fs.WalkDir 函数里。

官方地址：https://pkg.go.dev/io/fs#WalkDir

先把两种来源统一成 fs.FS

fs.FS 是一个很小的接口：调用方只需要按名称打开文件。磁盘目录可以用 os.DirFS 固定一个根目录，嵌入资源则由 embed.FS 提供同样的能力。两者的差异被限制在变量初始化处，后面的遍历代码不再关心底层是磁盘还是只读资源。

嵌入资源通常会带一个目录前缀。如果希望磁盘和嵌入资源都从 . 开始遍历，可以用 fs.Sub 把嵌入树裁剪到相同的逻辑根：

package main

import (
    "embed"
    "fmt"
    "io/fs"
    "os"
)

// embeddedResources 把 assets 目录编译进程序，运行时只读。
//go:embed assets/*
var embeddedResources embed.FS

func main() {
    // 磁盘 FS 的根是 static，传入 . 就从 static 开始遍历。
    diskFS := os.DirFS("static")

    // 裁剪掉 embed.FS 的 assets 前缀，使两种来源都暴露同一个逻辑根。
    embeddedFS, err := fs.Sub(embeddedResources, "assets")
    if err != nil {
        panic(fmt.Errorf("准备嵌入资源失败: %w", err))
    }

    // 后续函数只依赖 fs.FS，不需要知道来源类型。
    if err := listFiles("磁盘", diskFS); err != nil {
        panic(err)
    }
    if err := listFiles("内置", embeddedFS); err != nil {
        panic(err)
    }
}

fs.Sub 不会复制文件内容，它返回一个带前缀映射的文件系统视图。这样做的价值是让后续的根路径、过滤条件和测试样例保持一致；如果不需要统一根，也可以直接对 embed.FS 的 assets 目录调用 WalkDir。

同一个 WalkDir 函数处理两类资源

fs.WalkDir 会访问根目录本身，并按目录项名称的词法顺序遍历。统一函数可以只负责三件事：遇到回调错误时决定是否停止，目录是否需要过滤，以及对普通文件执行资源处理。

func listFiles(source string, fileSystem fs.FS) error {
    // 根使用 .，符合 io/fs 对虚拟路径的约定。
    return fs.WalkDir(fileSystem, ".", func(path string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // entry 可能为 nil，尤其是根目录 Stat 失败时不能先调用 IsDir。
            if entry != nil && entry.IsDir() {
                // 当前目录不可读时跳过它，是否继续由业务决定。
                return fs.SkipDir
            }
            return fmt.Errorf("遍历 %s 的 %s 失败: %w", source, path, walkErr)
        }

        if entry.IsDir() {
            // 隐藏目录、缓存目录等可以在这里统一过滤。
            if entry.Name() == "cache" {
                return fs.SkipDir
            }
            return nil
        }

        // path 是可直接交给 fs.ReadFile 的虚拟路径。
        fmt.Printf("[%s] %s\\n", source, path)
        return nil
    })
}

这里的 entry 是 fs.DirEntry，不必为了判断目录先调用一次 Stat。这也是 io/fs.WalkDir 相比旧式 filepath.Walk 更适合抽象文件系统的一点：回调直接得到目录项，底层实现可以减少不必要的 Lstat。

路径统一用斜杠，不要混入本机分隔符

io/fs 的名称是虚拟路径：必须是 UTF-8、无根、斜杠分隔的元素序列，根目录用 . 表示。即使程序运行在 Windows 上，fs.WalkDir 传给回调的路径也使用 /。因此，跨来源的过滤和读取可以直接比较 assets/config.json 这样的字符串。

如果只是拼接 FS 内部路径，使用 path.Join 或直接使用固定的斜杠；filepath.Join 适合本机操作系统路径，不应该把它当成 fs.FS 的通用命名规则。

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

func readConfig(fileSystem fs.FS, dir string) ([]byte, error) {
    // path.Join 始终产生斜杠分隔的虚拟路径。
    name := path.Join(dir, "config.json")
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("非法 FS 路径: %q", name)
    }

    // fs.ReadFile 对磁盘 FS 和 embed.FS 都使用相同的调用方式。
    data, err := fs.ReadFile(fileSystem, name)
    if err != nil {
        return nil, fmt.Errorf("读取 %s 失败: %w", name, err)
    }
    return data, nil
}

不要把 /tmp/config.json、dir/../config.json 或带尾部斜杠的名称直接传入 FS。路径校验不仅能提前给出更清晰的错误，也能避免同一个资源在磁盘实现和嵌入实现中出现不同解释。

把根目录失败和子目录失败分开处理

WalkDir 的回调错误参数不是“遍历结束标志”。如果初始根目录的 Stat 失败，回调会收到根路径、nil 的目录项和错误；如果进入某个目录后 ReadDir 失败，回调会再次报告该目录的错误。代码必须先判断 walkErr，再决定返回原错误、跳过当前目录，还是记录后继续。

一个实用的选择是：配置目录缺失直接失败，单个可选资源目录不可读则记录并跳过。不要无条件返回 fs.SkipDir，否则根目录失败时可能掩盖真正原因；也不要在 entry == nil 时调用 entry.IsDir()。

用指标比较两种来源，而不是只凭感觉判断快慢

磁盘遍历受目录数量、缓存命中和存储介质影响，嵌入资源则主要受打包树大小和目录读取实现影响。对比时不要只打印总耗时，至少记录遍历次数、耗时和分配次数；同时保持根路径、过滤规则和文件数量一致。

func benchmarkWalk(b *testing.B, fileSystem fs.FS) {
    b.Helper()

    // 每轮只统计遍历本身，避免初始化 FS 的成本污染结果。
    b.ReportAllocs()
    b.ResetTimer()
    for i := 0; i 

重点观察 ns/op、allocs/op 和遍历文件数。WalkDir 为保证确定性会按词法顺序读取目录项，因此一个包含大量同级文件的目录可能让目录读取和排序成为主要成本；这与资源来自磁盘还是嵌入并不是同一个维度。

最后的落地清单

• 装配层分别创建 os.DirFS、embed.FS，需要一致根路径时再用 fs.Sub。
• 业务层只接收 fs.FS，使用一个 fs.WalkDir 函数完成过滤和索引。
• FS 内部路径统一使用 /，拼接时优先用 path.Join，并在外部输入处检查 fs.ValidPath。
• 错误处理先判断 walkErr 和 entry == nil，再决定终止或跳过；不要把跳过当成成功。
• 用相同测试树和 b.ReportAllocs() 比较耗时、分配与文件数，避免用单次运行的体感下结论。

相关问题

embed.FS 可以写入文件吗？不可以。它是只读的 fs.FS 实现，适合读取模板、静态资源和默认配置；需要写入时应使用明确的磁盘目录或其他可写存储。

为什么不直接用 filepath.WalkDir？filepath.WalkDir 面向本机文件系统并返回操作系统分隔符；当同一套逻辑还要处理 embed.FS、fstest.MapFS 或其他虚拟 FS 时，io/fs.WalkDir 的统一接口更合适。

WalkDir 会跟随符号链接吗？目录中的符号链接默认不会被跟随；根本身如果是符号链接，则会遍历其目标。需要安全边界时，还要结合底层 FS 的实现和路径权限单独设计。