Go embed.FS 通过 fs.ValidPath 校验资源名时要注意什么

当 embed.FS 根据请求参数读取模板、配置或静态资源时，先调用 fs.ValidPath 是必要的边界检查，但它不是“路径清洗器”。它只判断名字是否符合 io/fs 的命名规则：路径使用斜杠分隔、不能包含空路径段、. 或 ..，也不能以斜杠开头或结尾；单独的 . 代表根目录。

先看清 fs.ValidPath 校验的到底是什么

io/fs 的接口在不同操作系统上都采用同一套路径语法。资源名是 UTF-8、未带根的斜杠路径，例如 templates/email.html。因此，下面这些结果很适合直接写进单元测试：

特别容易误会的是反斜杠。官方规则允许它作为普通字符，所以 fs.ValidPath(`assets\logo.svg`) 可能返回 true；但这不是 assets/logo.svg 的别名。embed.FS 仍按斜杠层级查找，二者通常对应不同的资源名。

校验后直接进入 embed.FS，不要切换成本地路径

更稳妥的做法是把请求名当作 io/fs 名字处理：先拒绝不合法输入，再把原字符串交给 fs.ReadFile。这样不会因为当前系统是 Windows 就把反斜杠、盘符或清洗结果带进另一套路径语义。

package assets

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

//go:embed templates/*
var content embed.FS

func readTemplate(name string) ([]byte, error) {
    // 先限制 io/fs 名字；不要用 filepath.Clean 替用户改写资源名。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid embedded resource name %q: %w", name, fs.ErrInvalid)
    }

    data, err := fs.ReadFile(content, name)
    if err != nil {
        // 格式错误和资源缺失是两种不同的调用方问题。
        if errors.Is(err, fs.ErrNotExist) {
            return nil, fmt.Errorf("embedded resource %q was not found: %w", name, err)
        }
        return nil, err
    }
    return data, nil
}

这里的关键不是把输入“变干净”，而是固定数据流：请求名 → ValidPath → embed.FS。如果业务允许用户传入带前缀的名字，可以在业务层明确去掉一个固定前缀后再校验；不要用通用清洗函数偷偷改变目录层级。

用错误类型判断“路径坏了”还是“资源没有”

fs.ReadFile 在底层调用文件系统的 Open，失败时通常返回带操作名和路径的 *fs.PathError。对外返回 HTTP 400 还是 404，应该依据错误原因，而不是看到所有读取失败都返回同一个状态。

func loadForRequest(name string) ([]byte, string, error) {
    // 非法名字属于请求格式问题，不能继续查询文件系统。
    if !fs.ValidPath(name) {
        return nil, "bad-name", fs.ErrInvalid
    }

    data, err := fs.ReadFile(content, name)
    if err == nil {
        return data, "ok", nil
    }
    // embed.FS 中合法但未嵌入的名字，通常落到不存在分支。
    if errors.Is(err, fs.ErrNotExist) {
        return nil, "missing", err
    }
    return nil, "read-failed", err
}

不要只判断错误字符串，也不要把 fs.ValidPath 当成资源存在性检查。templates/welcome.html 可能完全合法，但如果 //go:embed 没有匹配它，读取仍然会失败。

上线前用一组边界样例锁住约定

建议至少覆盖根目录、普通文件、目录穿越、绝对路径、重复斜杠和反斜杠。测试的目标是确认团队约定，而不是证明某个清洗函数“足够安全”。

func TestEmbeddedNameRules(t *testing.T) {
    cases := map[string]bool{
        ".":                  true,  // 根目录是 ValidPath 的特殊合法值。
        "templates/mail.html": true,  // 斜杠路径可交给 embed.FS。
        "":                   false, // 空名字不是根目录。
        "/templates/mail.html": false, // fs 路径不能以斜杠开头。
        "templates//mail.html": false, // 空路径段会被拒绝。
        "../mail.html":       false, // 父目录元素会被拒绝。
        `templates\\mail.html`: true, // 反斜杠可作为字符，但不等价于斜杠。
    }
    for name, want := range cases {
        if got := fs.ValidPath(name); got != want {
            t.Errorf("ValidPath(%q) = %v, want %v", name, got, want)
        }
    }
}

表面上看，反斜杠得到 true 似乎放宽了校验；实际上它提醒我们：io/fs 路径和操作系统路径是两种协议。只要后续始终调用 embed.FS 或其他遵守 io/fs 规范的实现，就不会把它误当成目录分隔符；如果还要访问磁盘，则必须另做面向操作系统路径的安全设计。

相关问题

fs.ValidPath(".") 为什么是合法的？

. 是 io/fs 约定的根目录名称，其他包含 . 的路径段仍然会被拒绝。

ValidPath 返回 true 就一定能读到文件吗？

不一定。它只说明名字符合语法；资源是否被 //go:embed 匹配，还要由实际文件系统读取决定。

可以先 filepath.Clean 再调用 embed.FS 吗？

不建议。filepath.Clean 使用操作系统路径语义，可能改变请求的目录层级；嵌入资源应保持斜杠名字并直接校验。