Go fs.WalkDir 与 filepath.WalkDir 怎么选：跨平台遍历目录的取舍

做目录扫描时，真正要先确定的不是“哪个 API 更新”，而是数据来自本机磁盘还是一个实现了 fs.FS 的抽象文件系统。要扫描用户机器上的目录，filepath.WalkDir 更顺手；要让同一段代码也能处理 embed.FS、测试内存文件系统或其他文件系统实现，fs.WalkDir 更合适。

本机路径和操作系统规则优先选 filepath.WalkDir；可替换文件系统和稳定的斜杠路径优先选 fs.WalkDir。两者都用 fs.DirEntry，但不能只看回调签名就忽略路径来源。

先按输入边界选 API，而不是按函数名选 API

如果任务是扫描 /var/log/myapp、用户上传目录或工作目录，输入本身就是操作系统路径，filepath.WalkDir 可以直接工作。它使用目标系统的路径规则，Windows 上回调路径可能包含反斜杠。

如果任务是读取编译进二进制的模板，通常先得到 embed.FS；如果测试要替换磁盘，通常会传入另一个 fs.FS。这时调用 fs.WalkDir，根目录写成 . 或类似 templates 的斜杠路径，代码就不绑定本机磁盘。

两个 WalkDir 共享回调，但路径语义不同

下面的回调只做一件事：找出扩展名为 .go 的普通文件。fs.DirEntry 可以先提供名称和类型信息，需要更完整的元数据时再调用 d.Info()，避免一上来就为每个文件取完整信息。

func collectGoFiles(root string) ([]string, error) {
    var found []string
    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if !d.IsDir() && filepath.Ext(d.Name()) == ".go" {
            found = append(found, path)
        }
        return nil
    })
    return found, err
}

这段代码适合真实磁盘。若把入口换成 fs.WalkDir，回调内部的筛选逻辑可以保留，但路径拼接和扩展名判断应使用面向斜杠路径的 path 包，或者只依赖 d.Name()，避免把本机分隔符带进抽象文件系统。

fs.WalkDir 把文件系统替换能力留在调用方

抽象版本的关键不是函数名，而是第一参数。生产代码可以用 os.DirFS 把本机目录暴露成 fs.FS；测试时则可换成 fstest.MapFS，不需要创建临时目录。

func listTemplates(fsys fs.FS) ([]string, error) {
    var names []string
    err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if !d.IsDir() && pathpkg.Ext(path) == ".tmpl" {
            names = append(names, path)
        }
        return nil
    })
    return names, err
}

调用链是 fs.WalkDir → fs.DirEntry → pathpkg.Ext → names。这里的 path 始终按 io/fs 规则使用斜杠，适合把结果作为嵌入资源名或配置键保存。

注意，示例中的导入别名 pathpkg 只是为了和回调参数 path 区分；完整程序里应明确写成 pathpkg "path"，不要把它误当成 filepath。

用这张表处理常见选择

别忽略错误、跳过目录和符号链接

两个 API 的回调都可能收到非空 err。例如目录读取失败时，先返回错误通常比继续使用空的 d 更安全。确定某个目录不需要深入时，返回 fs.SkipDir；想让整个遍历停止，可返回 fs.SkipAll。

两者都不跟随目录中的符号链接。若业务要求追踪链接，不能靠改一个回调条件实现，还需要明确处理循环链接、访问范围和重复路径。这里先别急着加“递归跟随”，目录扫描的安全边界往往比少扫几个文件更重要。

落地前做三次核对

1. 核对输入类型：是本机路径，还是 fs.FS？如果未来要支持 embed.FS，尽早让业务函数接收 fs.FS。
2. 核对路径格式：结果要传给操作系统，还是要作为资源名、URL 风格键或测试快照？前者偏向 filepath.WalkDir，后者偏向 fs.WalkDir。
3. 核对失败行为：目录权限错误、空目录、跳过目录和符号链接是否都有测试，且回调不会在 d == nil 时调用方法。

相关问题

filepath.WalkDir 比 fs.WalkDir 更快吗？

不能只按函数名下结论。两者都使用 fs.DirEntry 回调；实际耗时取决于文件系统实现、目录规模、回调工作和是否调用 Info。

fs.WalkDir 能扫描本机目录吗？

可以先用 os.DirFS 包装本机目录，再以 . 或其下的相对路径调用；如果不需要抽象层，直接用 filepath.WalkDir 更直观。

为什么不继续使用 filepath.Walk？

filepath.WalkDir 的回调使用 fs.DirEntry，通常能避免对每个访问项都先获取完整 FileInfo。新代码若只需名称和类型，应优先考虑它。

小结

filepath.WalkDir 解决“按本机路径走一遍目录树”，fs.WalkDir 解决“对任意 fs.FS 做同一套遍历”。先看输入和输出的路径语义，再看回调细节；这样既能保留跨平台能力，也不会把嵌入资源误写成本地文件操作。