Go io/fs.ValidPath 为什么拒绝 ./config.yaml：FS 路径规则与迁移边界

把某个文件夹挂载为 fs.FS 之后，不少人第一次读配置文件时会顺手写成 ./config.yaml，结果发现 fs.ValidPath 返回了 false，后续的 fs.ReadFile 调用直接报错。问题根本不是目标文件不存在，而是 io/fs 定义的合法名字和操作系统路径规则不一样：统一用斜杠做分隔符，不能用点号段开头，也不允许存在多余的跳转路径元素。

你写的 ./config.yaml 之所以被 ValidPath 拒绝，核心原因是 io/fs 规范里的公开路径不允许以 ./ 这类点号前缀开头，不属于操作系统原生路径的适配范围。

为什么 ./config.yaml 看起来正确，却不是合法 FS 路径

fs.FS 已经把根路径做了抽象封装。调用方拿到的不是“从当前工作文件夹开始的路径”，而是挂载点内部的独立名字，因此 config.yaml 表示根路径下的文件，env/prod.yaml 表示一个子文件夹里的文件。

fs.ValidPath 的判断可以单独抽出来跑一遍，排查问题时比直接看底层错误提示要清晰很多：

package main

import (
    "fmt"
    "io/fs"
)

func main() {
    for _, name := range []string{"config.yaml", "env/prod.yaml", "./config.yaml", "env/../config.yaml", ""} {
        fmt.Printf("%-22q valid=%v\n", name, fs.ValidPath(name))
    }
}

输出结果里，config.yaml、env/prod.yaml 和空字符串属于合法值；带 ./、.. 的名字都是无效的。空字符串代表 FS 根，不等于一个可以直接读取的普通文件。

fs.FS、os.DirFS 和 filepath 各自负责什么

这三个接口经常被放在一起混用，实际属于不同的处理层级。os.DirFS("./configs") 只负责把本地磁盘文件夹挂载成 FS 实例；调用 fs.ReadFile 时传入的名字必须严格遵守 io/fs 规则。filepath.Join 则面向本机文件系统，在 Windows 环境下会生成反斜杠分隔的路径，不能直接当作 FS 合法名字传入。

这里不要急着把所有路径字符串都交给 filepath.Clean 处理。它可能把 env/../config.yaml 整理成 config.yaml，但这不等于调用方原本的输入名字就应该被接受；路径清理和权限校验是完全独立的两件事。

迁移旧读取代码时，先固定输入语义

假设旧代码直接从磁盘文件夹读取配置：

func readConfig(root, name string) ([]byte, error) {
    return os.ReadFile(filepath.Join(root, name))
}

迁移到 fs.FS 之后，推荐把挂载根和内部访问名字拆分开维护：

func readConfig(fsys fs.FS, name string) ([]byte, error) {
    if !fs.ValidPath(name) || name == "" {
        return nil, fmt.Errorf("invalid config name: %q", name)
    }
    return fs.ReadFile(fsys, name)
}

func main() {
    configs := os.DirFS("./configs")
    data, err := readConfig(configs, "env/prod.yaml")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(len(data))
}

测试场景下用 fstest.MapFS 可以脱离真实磁盘文件夹验证边界逻辑：

func TestReadConfigRejectsDotPath(t *testing.T) {
    mem := fstest.MapFS{"config.yaml": &fstest.MapFile{Data: []byte("ok")}}
    if _, err := readConfig(mem, "./config.yaml"); err == nil {
        t.Fatal("expected invalid FS name")
    }
}

允许子文件夹参数时，哪些输入应该直接拒绝

如果名字来自命令行参数或外部配置文件，建议统一把它当作 FS 内部名字处理，并且保留原始输入值用于后续报错提示。下面的检查逻辑覆盖了最容易被忽略的三类问题：

• 空字符串：它是挂载根标记，不是合法的配置文件名。
• 以 ./ 开头或包含 .. 的路径：不要先做清理再放行。
• 包含反斜杠：这是 Windows 操作系统的原生路径习惯，不是可跨平台移植的 FS 名字。

如果业务确实需要接收用户传入的磁盘路径，就不要伪装成 FS 名字处理；在磁盘路径层完成挂载根范围约束，再用 os.Open 读取。两种语义混用的话，很容易出现 Linux 环境能正常读取、Windows 环境读不到，或者本地测试通过但打包后的 embed.FS 运行失败。

常见问题：ValidPath 相关的几个边界

fs.ValidPath(".") 为什么是 true？

. 表示 FS 挂载根，是合法的 FS 名字；它和空字符串都不适合作为普通文件传给读取函数。

fs.FS 里能不能使用 Windows 反斜杠？

不能把反斜杠当合法分隔符。统一使用正斜杠，需要拼接 FS 名字时优先使用 /，需要拼接 FS 名字时优先使用 path.Join。

filepath.Clean 能不能代替 fs.ValidPath？

不能。filepath.Clean 是路径整理工具，fs.ValidPath 才是 FS 名字的规则校验；前者不应该承担安全放行的职责。

把路径规则写进测试，迁移时就不容易回退

这类问题通常不是业务逻辑复杂，而是接口边界没有写成明确约束。至少为正常文件、子文件夹、./、..、空名字和反斜杠各编写一个表驱动测试用例。等测试逻辑固定后，再把 os.DirFS、embed.FS 或 fstest.MapFS 换进来，上层读取业务代码不需要跟着改动。