Go io/fs.ValidPath校验虚拟文件路径的使用边界

我第一次把 embed.FS 接到模板加载器时，真正让我停下来的不是文件不存在，而是同一个资源名在不同入口表现不一致：assets/logo.svg 能打开，./assets/logo.svg、/assets/logo.svg 和 Windows 风格的 assets\logo.svg 却不能按普通磁盘路径理解。这里的统一答案是先用 fs.ValidPath 检查虚拟路径，再把通过检查的字符串交给 fs.FS。

官方资料：https://pkg.go.dev/io/fs

先固定 ValidPath 的输入输出边界

fs.ValidPath(name) 只回答一个问题：这个字符串是否可以作为 FS.Open 的路径名。它不是“文件是否存在”检查，也不会访问磁盘。.、config/app.yaml 和 assets/icon.svg 是有效示例；空串、..、/config/app.yaml、config/、config//app.yaml、config/./app.yaml 都应判为无效。

package main

import (
    "fmt"
    "io/fs"
)

func main() {
    paths := []string{".", "config/app.yaml", "", "../secret", "/etc/hosts", "assets\\icon.svg"}
    for _, name := range paths {
        // ValidPath 只校验 io/fs 的虚拟路径语法，不判断目标文件是否存在。
        fmt.Printf("%q -> %t\n", name, fs.ValidPath(name))
    }
}

要特别记住，反斜杠和冒号本身可以出现在有效路径中；契约要求的是 FS 实现不能把它们继续解释成路径分隔符。因此，assets\\icon.svg 可能通过语法校验，但它不等于 assets/icon.svg。

在业务入口统一拒绝不合规路径

我更愿意把校验放在资源读取函数最前面，而不是让每个调用者猜测 Open 返回的具体错误。这样，空路径和绝对路径会在进入 FS 前被归类为参数错误；通过校验后，读取失败才代表文件不存在、权限不足或底层实现错误。

package assets

import (
    "fmt"
    "io/fs"
)

func Read(fsys fs.FS, name string) ([]byte, error) {
    // 先挡住绝对路径、.. 和重复分隔符，避免混入宿主机路径语义。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid virtual path %q", name)
    }
    // ReadFile 会继续使用 FS 的 Open 规则，并负责关闭打开的文件。
    return fs.ReadFile(fsys, name)
}

这一层不要偷偷调用 path.Clean 把非法输入“修好”。例如 a/../b 被清成 b 后，调用方已经失去了原始输入边界；如果资源名来自请求参数、归档索引或模板变量，直接拒绝通常更容易审计。

处理 Windows 字符与业务路径拼接

io/fs 的路径在所有系统上都使用 /。因此，跨平台代码不要用 filepath.Join 生成 FS 路径：它表达的是宿主机文件系统路径，Windows 下可能产生反斜杠。对于已知的虚拟路径片段，应使用 path.Join，但拼接后仍要再做一次 ValidPath，因为片段可能来自外部输入。

让 FS 实现和测试复用相同契约

标准库文档要求 FS.Open 拒绝不满足 ValidPath 的名称，并返回带有 ErrInvalid 或 ErrNotExist 的 *fs.PathError。自定义 FS 不应只在外层包装函数里校验，Open 本身也要守住接口边界；否则直接使用该 FS 的调用者仍可能得到不一致行为。

func (m memFS) Open(name string) (fs.File, error) {
    // 自定义 FS 的核心入口也复用标准路径契约。
    if !fs.ValidPath(name) {
        return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrInvalid}
    }
    file, ok := m.files[name]
    if !ok {
        return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
    }
    return file, nil
}

测试时建议把语法边界和存在性边界分开：先断言非法名称得到 ErrInvalid，再用一个合法但不存在的名称断言 ErrNotExist。这种分层能防止后续把“路径拼错”和“资源缺失”混成一个问题。

常见问题

fs.ValidPath("") 为什么不把空串当根目录？

在 io/fs 中，根目录使用 . 表示；空串没有稳定的目录含义，所以应直接拒绝。

能不能先用 filepath.Clean 再调用 ValidPath？

不建议。清理会改变输入的语义，尤其会吞掉 .. 和重复分隔符。先校验原始虚拟路径，业务确实需要转换时再明确记录映射规则。

反斜杠通过校验是不是代表可以访问 Windows 文件？

不是。它最多说明字符串符合语法；FS 实现不能把反斜杠当分隔符，具体资源名是否存在仍由 FS 决定。

自定义 FS 只在外层校验够不够？

不够。直接实现 fs.FS 时，Open 入口也应执行同一规则，让所有调用路径的错误分类保持一致。

实际项目里，我会把 ValidPath 当作虚拟资源协议的一部分：先拒绝不符合契约的输入，再处理路径拼接和资源存在性。这样 embed.FS、os.DirFS 和自定义 FS 都能用同一张检查清单，跨平台行为也更容易预测。