Go fs.WalkDir 怎样读取嵌入文件系统

Go fs.WalkDir 可以直接遍历 embed.FS，因为后者实现了 fs.FS。读取内容需要在回调中另外调用 fs.ReadFile(fsys, name)：WalkDir 提供条目和路径，本身不读取每个文件的正文。遍历和读取必须使用同一个文件系统及其路径空间。

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

从部署后找不到资源，转向统一的文件系统接口

一个命令行工具在源码目录能读取模板，换个启动目录却找不到文件，这是外部文件相对路径依赖带来的典型场景。若模板与程序版本绑定，把资源编译进二进制可以减少部署时遗漏文件的机会。这里讨论一种可采用的工程路径，不把示例当作真实故障记录，也不声称有独立的流行度数据。

收益是资源与程序一起交付，代价是更新资源需要重新构建。经常变化的用户配置、上传文件和运行日志仍应放在外部存储，不适合因为接口方便就全部内嵌。

解决两个问题：条目遍历与内容读取

例如原始资源中的 assets/help.txt，在对子树调用 fs.Sub 后，名称是 help.txt。此时若把 help.txt 再拿到原始 resources 上读取，就换了路径空间，可能得到不存在错误。也不要用 os.ReadFile 读取回调路径，它访问的是磁盘，而非二进制里的资源。

采用示例：先列出资源，再读取正文

下面适用于至少支持 embed 的 Go 工具链。准备一个独立包，放入 main.go，并创建 assets/help.txt 和 assets/messages/notice.txt 两个非空文本文件。内容可以分别写“帮助入口”和“资源已绑定”。示例没有运行结果截图，也没有在本任务执行代码。

package main

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

// assets 目录必须位于当前包内，并至少含一个可嵌入文件。
//go:embed assets
var resources embed.FS

func listText(fsys fs.FS) error {
    return fs.WalkDir(fsys, ".", func(name string, d fs.DirEntry, walkErr error) error {
        // 根路径出错时 d 可能为 nil，先处理错误再访问条目。
        if walkErr != nil { return fmt.Errorf("遍历 %s: %w", name, walkErr) }
        if d.IsDir() { return nil }
        // 用回调完整路径及同一个文件系统读取，不依赖进程工作目录。
        data, err := fs.ReadFile(fsys, name)
        if err != nil { return fmt.Errorf("读取 %s: %w", name, err) }
        fmt.Printf("%s: %q\n", name, string(data))
        return nil
    })
}

func main() {
    // 把 assets 子树作为逻辑根；回调路径不再带 assets 前缀。
    sub, err := fs.Sub(resources, "assets")
    if err != nil { log.Fatal(err) }
    if err := listText(sub); err != nil { log.Fatal(err) }
}

按这个目录布局构建后，逻辑上应打印 help.txt 与 messages/notice.txt 的路径和引用后的正文。WalkDir 会访问根目录“.”，回调遇到目录就返回 nil，文件才进入 ReadFile。d.Name() 只给基名，深层文件读取应使用回调的完整 name，避免不同目录同名文件被混淆。

fs 的路径使用正斜杠，不以斜杠开头或结尾，根使用“.”。不要把操作系统绝对路径或反斜杠拼接结果传给它。fs.WalkDir 与 filepath.WalkDir 的目标不同：前者接受文件系统接口，后者处理操作系统路径。

谁会受益，哪些边界需要提前接受

固定模板、帮助文档和小型内置规则的维护者，通常更容易从统一接口受益。业务函数像 listText 一样接收 fs.FS，调用方可以明确提供资源来源，减少函数内部隐含的磁盘路径。能否改善部署可靠性取决于原来的资源交付方式，这是工程判断，并非性能承诺。

embed.FS 是只读的，磁盘文件在构建后变化不会修改已有二进制中的内容。直接嵌入目录时，遍历匹配默认排除名称以点或下划线开头的文件；需要改变这一规则时可了解 all: 前缀，并明确哪些文件允许打进产物。空目录不会作为独立有效资源被保存，嵌入模式没有匹配到有效文件则构建失败。

ReadFile 一次取得全部内容，适合这里的小文本，不应把它泛化成无上限加载大资源的方案。WalkDir 按字典顺序遍历，为此要先读取一个目录的全部条目；大目录仍需关注条目数量和内存成本。

过滤与错误处理，决定遍历能否完整结束

回调错误不应被一律忽略。初始根访问失败时 d 可能为 nil，必须先判断 walkErr。下面片段用于过滤目录和扩展名，需在原回调错误判断之后使用，并增加 path 包导入：

// 在 WalkDir 回调中，先处理 walkErr，再做以下目录过滤。
if d.IsDir() && name == "draft" {
    return fs.SkipDir // 只在目录上返回，跳过其整个子树。
}
if d.IsDir() { return nil }
// 普通文件不匹配时返回nil，不能用SkipDir代替“跳过这个文件”。
if path.Ext(name) != ".txt" { return nil }

SkipDir 在目录上表示跳过子树，在普通文件上却会跳过其父目录的剩余遍历，不能用它代替“跳过当前文件”。无需读取某个普通文件时返回 nil 即可。返回其他非 nil 错误会终止整个遍历，适合资源不可缺失的初始化过程。

采用路径与观察指标

建议从一组与版本绑定的小资源开始，先固定逻辑根，再把遍历函数改为接收 fs.FS。确认旧的磁盘读取调用没有混入同一条路径后，再扩大覆盖。保留资源的来源文件与构建版本，更新时重新构建和交付；不需要通过修改进程工作目录补救内嵌路径问题。

• 关注是否存在预期文件、成功读取的条目数与总字节数，避免只看遍历函数是否被调用。
• 区分匹配阶段的构建错误、根路径错误和正文读取错误，记录逻辑名称即可，敏感内容不写日志。
• 核对内嵌资源对产物大小及初始化内存的影响，不虚构性能提升。
• 目录缺失或文件数变化要回到嵌入模式和构建产物判断，而非默认归因于运行目录。

从“.”开始会把整个电脑遍历一遍吗？不会，它是传入fs.FS的根。更改资源文件后为什么没变化？运行中的二进制仍保存构建时内容，需要重新构建并运行新产物。只要文件名就够了吗？深层资源需要回调的完整路径，基名可能重名。内嵌资源能写回吗？embed.FS只提供只读内容，需要持久化修改应使用外部存储。