Go io/fs 遍历嵌入资源的路径处理方法

Go遍历嵌入资源时，路径必须相对于当前fs.FS对象，并使用斜杠分隔。原始embed.FS中的assets/readme.txt，在fs.Sub(resources, "assets")返回的视图里应写成readme.txt；遍历该子视图的根目录用"."，不是空字符串或"/"。

官方文档：https://pkg.go.dev/io/fs

把路径与文件系统对象一起传递

假设一个命令行程序把帮助文本打包进可执行文件。调用方想列出文本资源，却一会儿使用assets前缀、一会儿去掉前缀，读取就会指向不同位置。这个原创假设场景的解决方法，是把文件系统对象与相对路径看作一对，而不是在各函数中随意增删目录名。

这里可以称为“资源根视图”：通用遍历函数接收fs.FS和root，由调用方确定根的位置。它适合帮助文件、模板和静态资源的共享读取逻辑。代价是所有传入和返回路径都要说明属于哪个视图，不能把“字符串一样”当成“文件一样”。

一份资源树，两种遍历入口

读者可在自己的示例目录准备以下结构。这是准备约定，不是本机已有文件列表。目录中的文本内容自定，大小不作固定假设。

demo/
  main.go
  assets/
    readme.txt
    guide/
      start.txt
    drafts/
      notes.txt

drafts在本例中是明确跳过的业务目录，并非嵌入功能自动排除它。将下列完整原创代码保存为main.go；嵌入资源编译时须已经存在，普通embed目录模式忽略空目录，并对无匹配或非法模式报构建错误。

package main

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

// assets相对本源文件所在包目录；普通目录模式不包含点或下划线开头文件。
//go:embed assets
var resources embed.FS

func listText(fsys fs.FS, root string) error {
    return fs.WalkDir(fsys, root, func(name string, entry fs.DirEntry, walkErr error) error {
        // 先处理错误；根路径访问失败时entry可能为nil。
        if walkErr != nil {
            return fmt.Errorf("遍历%q: %w", name, walkErr)
        }
        if entry.IsDir() {
            if entry.Name() == "drafts" {
                return fs.SkipDir // 仅用于本例业务上不读取的草稿目录。
            }
            return nil
        }
        if path.Ext(name) != ".txt" {
            return nil // 普通文件筛选不用SkipDir。
        }
        // name属于传入fsys，读取时不换成另一个文件系统对象。
        data, err := fs.ReadFile(fsys, name)
        if err != nil {
            return fmt.Errorf("读取%q: %w", name, err)
        }
        _, err = fmt.Printf("%s: %d字节\n", name, len(data))
        return err
    })
}

func run() error {
    fmt.Println("原始资源视图")
    if err := listText(resources, "assets"); err != nil {
        return err
    }
    assetView, err := fs.Sub(resources, "assets")
    if err != nil {
        return fmt.Errorf("创建子视图: %w", err)
    }
    fmt.Println("子资源视图")
    // Sub建立路径视图；实际遍历仍可能返回目录不存在等错误。
    return listText(assetView, ".")
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

这个函数直接调用fs.ReadFile读取同一fsys中的name，不把它转为本地磁盘路径。fs.ReadFile返回整份文件内容，适合本例短文本；如果资源很大，遍历名字并不意味着内容读取自动变成流式，需另选Open和适当读取方式，并关闭打开的文件。

Sub改变根视图，不会改文件内容

原始resources保留assets层级；assetView以assets为根，名字自然少了一层。fs.Sub不是移动资源，也不是从可执行文件解压到磁盘。子视图创建成功不应被泛化为目标目录已存在，随后遍历或读取还须处理错误。

典型反例是从assetView遍历得到guide/start.txt，却用resources读取这个名字，或在assetView内继续读取assets/guide/start.txt。两者都混用了坐标系。回调返回的name属于本次WalkDir传入的fsys，继续交给这个对象即可，不必手工切字符串。

io/fs路径不是操作系统路径

io/fs采用统一的无根、斜杠分隔名字，不随宿主操作系统改变。不要用filepath.Join生成嵌入资源名；需要拼接固定资源名时使用path包。fs.ValidPath能检查路径形式，但返回true不证明文件存在，也不表示业务允许访问。

例如guide/start.txt是合适的资源名；/guide/start.txt、guide/、guide/../readme.txt不是同一有效形式。根目录的特殊名字是单独的点。反斜杠在io/fs中不充当目录分隔符，不能把Windows本地路径直接当成资源路径。

如果业务只允许某一组文件，还需另设明确的允许范围。不要先path.Clean再把本来带上跳片段的外部输入悄悄接纳为其他合法名字；校验输入语法和决定访问范围是两回事。本篇只讨论固定嵌入资源，不实现外部请求路由。

目录回调先处理错误，再筛选条目

WalkDir回调涵盖根目录和子条目。发生访问错误时先处理walkErr，不能先调用entry.IsDir而假设entry始终非空。本例选择返回错误而非忽略，让调用方知道列表并非完整。

目录drafts使用fs.SkipDir跳过整个子树；普通非txt文件返回nil。SkipDir若被误用于普通文件，会跳过包含该文件的目录中后续访问内容，不是“只跳过这个文件”。本例通过IsDir分支将用途限制在目录。

资源集合还由编译时go:embed模式决定。普通目录模式对点或下划线开头名字的排除，不能误判为WalkDir漏遍历；确需包含这些资源，应依据embed规则选择合适模式，不无差别包含敏感文件。嵌入后资源不随运行时工作目录变化。

结果应怎样理解

按示例树，原始视图的txt文件名应包括assets/guide/start.txt和assets/readme.txt；子视图对应guide/start.txt和readme.txt；草稿文件被本例规则跳过。程序还打印各文件字节数，它随实际内容变化。上述是代码逻辑的预期，不是实测日志。

# 在自己准备好main.go与assets目录后运行；不创建或覆盖资源文件。
go run main.go

如果查不到文件，依次确认编译时是否被嵌入、传入哪个FS对象、root和name是否相对于它，以及回调是否忽略了错误。不要靠改变工作目录修补embed路径。

常见问题

fs.Sub返回后可以直接用空字符串遍历吗？根目录应使用点；空字符串不是有效的io/fs根名字。

修改磁盘上的assets文件，已经构建的程序会更新吗？嵌入内容来自构建时的资源，更新后须重新构建；它不是运行时磁盘加载。

DirEntry.Name能直接当完整路径吗？它仅是末尾名称。嵌套资源继续使用回调name，避免丢失目录层级。

把FS换成磁盘实现就等于安全沙箱吗？不能这样推断。fs.FS是访问接口抽象，Sub也不自动为所有实现提供操作系统隔离；嵌入资源路径处理与磁盘安全策略应分别设计。

这套做法的判断标准很简单：每个名字都明确属于哪个FS，通用函数不猜前缀，错误不被吞掉。资源根统一后，目录遍历和文件读取就能保持同一套相对路径约定。

嵌入规则官方文档：https://pkg.go.dev/embed