Go embed.FS 与 fs.WalkDir 如何筛选配置文件：目录遍历和错误传播

服务发布后不希望再依赖容器里的配置目录，但又需要在启动时检查一批内置 YAML 文件，embed.FS 和 fs.WalkDir 正好把这件事拆成两步：先得到只读文件树，再沿着文件树遍历并按路径筛选。真正容易出错的地方不是“能不能找到文件”，而是目录名、扩展名和遍历错误有没有被明确处理。

把 config/ 作为嵌入根目录，使用 fs.WalkDir 遍历时先判断 err，再判断 DirEntry 是否为目录，最后筛选 .yaml 文件；任何遍历错误都应该原样返回。

先固定嵌入根目录和文件路径

示例工程把配置放在当前 Go 包下的 config/ 目录中。embed.FS 是只读文件系统，路径使用斜杠，并且传给 fs.WalkDir 的根路径必须是嵌入文件树里的相对路径，而不是宿主机绝对路径。

package main

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

//go:embed config
var embedded embed.FS

func listConfigFiles() ([]string, error) {
    var files []string
    err := fs.WalkDir(embedded, "config", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            return nil
        }
        files = append(files, path)
        return nil
    })
    if err != nil {
        return nil, fmt.Errorf("walk config: %w", err)
    }
    return files, nil
}

这里的调用链很短：embedded 提供文件树，fs.WalkDir 逐项调用回调，回调把文件路径追加到 files，外层再处理 err。先保留这个最小版本，能清楚看出目录和普通文件的分支。

把目录遍历变成可控的 YAML 筛选

如果配置目录里同时有 README、示例文件或子目录，直接把每个非目录项都当配置会让加载阶段变得脆弱。筛选动作应放在 d.IsDir() 之后，只让以 .yaml 结尾的路径进入结果。

import "strings"

func listYAMLFiles() ([]string, error) {
    var files []string
    err := fs.WalkDir(embedded, "config", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            return nil
        }
        if !strings.HasSuffix(path, ".yaml") {
            return nil
        }
        files = append(files, path)
        return nil
    })
    if err != nil {
        return nil, fmt.Errorf("walk yaml config: %w", err)
    }
    return files, nil
}

strings.HasSuffix 只负责后缀判断，不会验证 YAML 内容，也不会判断文件名是否符合业务命名规则。加载前还需要对列表排序或定义稳定的加载顺序；如果配置之间存在覆盖关系，更应该把顺序写成明确规则，而不是依赖目录遍历的偶然结果。

错误参数为什么必须排在 DirEntry 前面

fs.WalkDir 的回调签名包含 path、d 和 err。当某个路径无法读取时，回调可能带着错误进入；此时不能假定 d 一定可用。先返回 err，可以让外层拿到原始原因并决定是否终止启动。

另外，不要把回调里的错误改成一段没有上下文的字符串。外层用 %w 包装后，调用方仍能通过 errors.Is 或 errors.As 判断底层错误。对于嵌入文件树，构建阶段的路径错误通常更早暴露；但这个写法同样适用于 os.DirFS 等其他 fs.FS 实现。

用测试锁住目录层级和筛选结果

测试不要只检查“返回数量大于零”。把 config/app.yaml、config/dev.yaml 和一个非 YAML 文件放入测试树，逐个核对返回路径，才能防止后续重命名或过滤条件变化时悄悄漏载配置。

func TestListYAMLFiles(t *testing.T) {
    files, err := listYAMLFiles()
    if err != nil {
        t.Fatal(err)
    }
    want := []string{"config/app.yaml", "config/dev.yaml"}
    slices.Sort(files)
    if !slices.Equal(files, want) {
        t.Fatalf("files = %v, want %v", files, want)
    }
}

如果项目还要支持不止 YAML 的格式，可以把后缀集合提取成配置，但不要因此绕过错误分支。目录遍历的职责是发现路径，文件解析的职责是检查内容，两者分开后，启动失败的原因更容易定位。

常见问题：embed.FS 和 fs.WalkDir 怎么选

embed.FS 能在运行时写入文件吗？

不能。它提供的是只读文件系统；需要写入时应使用宿主机目录、数据库或其他明确的存储实现。

为什么根路径写成 config 而不是 ./config？

io/fs 使用斜杠分隔的相对路径，根目录应写成文件树中的有效路径，config 更直接也更容易测试。

回调里遇到不需要的目录能不能返回 fs.SkipDir？

可以。只有确定整个子目录都不需要时才跳过；如果只是过滤文件扩展名，应对普通文件返回 nil，继续遍历。

fs.WalkDir 会解析 YAML 内容吗？

不会。它只负责遍历并提供 fs.DirEntry，YAML 解析、字段校验和配置覆盖顺序需要由后续加载层负责。

这套写法的核心不是把代码压缩到最少，而是把边界写在回调里：err 先处理，目录再放行，文件最后按 .yaml 筛选。以后把 embed.FS 换成别的 fs.FS 实现时，遍历和业务过滤仍然可以原样复用。