Go io/fs 怎样遍历文件系统并保留相对路径完成一个可复用的最小示例

我第一次把目录遍历封装成小工具时，最容易混在一起的是“从哪里开始走”和“返回什么路径”。如果直接围着操作系统路径拼字符串，代码很快就会绑死在某个平台上。现在更稳的写法是：用 os.DirFS 固定一个目录作为文件系统根，再交给 fs.WalkDir 遍历。回调拿到的 path 本身就是相对路径，适合记录、展示和交给其他 io/fs API。

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

核心做法：os.DirFS("demo-data") 负责定义根，fs.WalkDir(fsys, ".", callback) 负责遍历；只有把路径交给操作系统 API 时，才在边界处调用 filepath.FromSlash。

先把根目录和路径语义固定下来

io/fs 的路径不是当前操作系统的原生路径。它要求路径使用 UTF-8、无根、斜杠分隔的形式，根目录用 . 表示。因此遍历 demo-data/docs/readme.md 时，回调拿到的是 docs/readme.md，而不是带磁盘前缀的绝对路径。

这层抽象的好处是，遍历逻辑可以接收任何实现了 fs.FS 的对象，不一定是本地磁盘，也可以是嵌入文件系统或内存文件系统。下面的示例先使用本地目录，便于把结果看清楚。

WalkDir 的回调为什么适合收集相对路径

我会把“遍历”和“收集”放在同一个小函数里，但不把绝对路径泄漏给调用方。DirEntry 足够判断当前项是不是目录；遇到普通文件时，直接保存回调给出的相对路径。

package main

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

// listFiles 返回 root 下普通文件的 io/fs 相对路径。
func listFiles(root string) ([]string, error) {
    // 把 root 设为文件系统根，后续路径不再带本机绝对前缀。
    fsys := os.DirFS(root)
    files := make([]string, 0)

    // 使用 . 表示 fsys 的根，path 始终是斜杠分隔的相对路径。
    err := fs.WalkDir(fsys, ".", func(path string, entry fs.DirEntry, walkErr error) error {
        // 访问目录项失败时不能继续使用 entry，应把原始错误交回遍历器。
        if walkErr != nil {
            return walkErr
        }

        // 目录由 WalkDir 继续展开；这里只收集普通文件。
        if entry.IsDir() {
            return nil
        }
        if entry.Type().IsRegular() {
            files = append(files, path)
        }
        return nil
    })
    if err != nil {
        return nil, fmt.Errorf("遍历 %q 失败: %w", root, err)
    }
    return files, nil
}

func main() {
    // 示例目录结构：demo-data/docs/readme.md、demo-data/config/app.yaml。
    files, err := listFiles("demo-data")
    if err != nil {
        fmt.Println(err)
        return
    }
    for _, path := range files {
        // 这里打印的是相对路径，不是带磁盘前缀的绝对路径。
        fmt.Println(path)
    }
}

这个函数最值得保留的是边界：调用方只知道 docs/readme.md 这种稳定名字，不需要知道目录实际位于哪个盘符或挂载点。对于打包资源、配置扫描和测试替身，这种返回值比绝对路径更容易复用。

我第一次不适应的地方：错误要先处理

WalkDir 的回调同时给出 path、DirEntry 和错误。如果某个目录项无法读取，entry 可能不可用；因此示例把 walkErr 放在回调第一段处理。返回错误会停止遍历，并由外层用 %w 保留原因。

另一个容易误判的点是路径转换。只要继续使用 fs.ReadFile(fsys, path) 或 fs.ValidPath(path)，就保持斜杠路径；只有调用 os.Open、filepath.Join 这类操作系统接口时再转换：

// path 是 WalkDir 返回的 io/fs 路径；交给操作系统 API 前再转换。
nativePath := filepath.Join(root, filepath.FromSlash(path))
file, err := os.Open(nativePath)
if err != nil {
    return fmt.Errorf("打开 %q 失败: %w", nativePath, err)
}
defer file.Close()

这里的转换不是为了“修正” WalkDir 的结果，而是把跨平台的逻辑路径送到本机文件 API 的最后一公里。

模式的代价与适用清单

把根目录和相对路径分开，是一个小而有用的抽象，但它不是万能遍历器。WalkDir 按目录读取顺序访问项目，结果适合确定性展示；它不会自动跟随符号链接。如果目录很大，直接把全部路径放入 []string 会占用与结果数量相关的内存，可以改成回调式消费或边遍历边写入。

我的判断清单只有三项：根目录是否明确、回调错误是否原样处理、路径是否只在 API 边界转换。三项都满足时，这个最小实现就足够作为可复用的文件索引基础。

相关问题

WalkDir 返回的是绝对路径吗？

不是。对 os.DirFS(root) 遍历时，回调路径相对于这个文件系统根，并使用 io/fs 的斜杠规则。

为什么不直接用 filepath.WalkDir？

如果任务只面向本机目录，filepath.WalkDir 也可以；需要让遍历逻辑适配嵌入文件、内存文件或统一的 fs.FS 接口时，io/fs.WalkDir 的边界更清楚。