fs.ValidPath 校验用户路径并避免越界访问的处理方案

我在把“用户输入的文件名”接到 Go 文件读取接口时，最容易犯的错是先拼接操作系统路径，再希望后面的清理函数替自己兜底。更稳妥的做法是先明确使用的是 io/fs 命名空间：用 fs.ValidPath 拒绝绝对路径、空路径和包含 ./.. 的元素，再把固定目录包装成 fs.FS，最后调用 fs.ReadFile 或 Open。

这套方案能把输入限制在相对的、斜杠分隔的文件名空间内，但它不是完整的操作系统安全沙箱。尤其是 os.DirFS 对目录内部的符号链接并不提供 chroot 级别的约束，是否需要更强的根目录边界，要单独选择对应的文件系统 API。

先把 ValidPath 的边界说清楚

fs.ValidPath 的职责很窄：判断一个路径名是否适合传给 FS.Open。合法输入是 UTF-8、未加根、使用斜杠分隔的路径，例如 .、readme.txt 和 docs/api.txt；空字符串、以斜杠开头或结尾、包含空元素、. 或 .. 的路径都会被拒绝。

这里的“斜杠”是 io/fs 的命名空间约定。官方文档还特别说明，反斜杠和冒号可以作为普通字符被接受，但 FS 实现不能把它们当作路径分隔符。因此不要把 ValidPath 当成 filepath.Clean 的替代品，也不要把它的返回值解释成“这个操作系统路径一定安全”。

package main

import (
    "fmt"
    "io/fs"
)

func main() {
    samples := []string{
        ".", "docs/api.txt", "", "../secret.txt", "/etc/hosts",
        "docs//api.txt", "docs/./api.txt", "docs/../api.txt",
    }

    for _, name := range samples {
        // ValidPath 只判断 io/fs 的路径语法，不执行文件读取。
        fmt.Printf("%q -> %t\n", name, fs.ValidPath(name))
    }
}

因此，用户输入的第一道门应该是 fs.ValidPath(name)。如果业务不允许读取根目录，还要额外拒绝 .；如果业务只接受某种扩展名，则在通过 ValidPath 后再做业务规则判断。

把固定目录改成 fs.FS

迁移时我会先把“宿主机目录”和“用户相对路径”拆成两个变量。os.DirFS(root) 负责把一个目录暴露为 fs.FS，调用方只接收相对路径名。这样业务代码不需要把用户输入和根目录用字符串直接拼接。

package files

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

var ErrInvalidName = errors.New("invalid file name")

func ReadUserFile(root, name string) ([]byte, error) {
    // 先拒绝不符合 io/fs 约定的名字，再进入固定根目录。
    if !fs.ValidPath(name) || name == "." {
        return nil, fmt.Errorf("%w: %q", ErrInvalidName, name)
    }

    // DirFS 将 root 作为 FS 的根；name 不再是宿主机绝对路径。
    fileSystem := os.DirFS(root)
    data, err := fs.ReadFile(fileSystem, name)
    if err != nil {
        // 保留 PathError，让上层仍能用 errors.Is 判断 ErrNotExist 等原因。
        return nil, fmt.Errorf("read %q: %w", name, err)
    }
    return data, nil
}

这个函数的关键不是“把字符串洗干净”，而是让每个参数有单一含义：root 是部署配置，name 是文件系统命名空间中的相对名字。若文件不存在，fs.ReadFile 返回的错误仍可通过 errors.Is(err, fs.ErrNotExist) 判断，调用方不必解析错误文本。

用 fs.Sub 收窄一个子目录

如果所有用户文件都位于固定根目录下的 public 子目录，可以先构造子文件系统，再让后续代码只处理子目录内的相对名字。fs.Sub 会返回对应子树的 FS；传入 . 时会原样返回原文件系统。

package files

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

func NewPublicFS(root string) (fs.FS, error) {
    // root 来自可信配置，public 是固定的应用目录，不接收用户输入。
    base := os.DirFS(root)
    public, err := fs.Sub(base, "public")
    if err != nil {
        return nil, fmt.Errorf("create public fs: %w", err)
    }
    return public, nil
}

func ReadPublicFile(fileSystem fs.FS, name string) ([]byte, error) {
    // 子文件系统已经固定目录，name 仍必须是合法相对路径。
    if !fs.ValidPath(name) || name == "." {
        return nil, fmt.Errorf("invalid public file name: %q", name)
    }
    data, err := fs.ReadFile(fileSystem, name)
    if err != nil {
        return nil, fmt.Errorf("read public file %q: %w", name, err)
    }
    return data, nil
}

这里有一个容易被忽略的限制：官方文档明确指出，os.DirFS 和 fs.Sub 不会因为目录映射就自动变成 chroot 安全机制；如果根目录内部存在指向外部目录的符号链接，仍需考虑它带来的访问范围。需要把目录树约束得更严格时，应评估当前 Go 版本提供的 os.Root 能力，而不是仅仅增加一层字符串检查。

错误链要保留，别把三类失败混成一个 400

实际接口里至少要区分三类情况：输入不符合命名空间规则、路径合法但目标不存在、路径存在但读取时发生权限或 I/O 错误。第一类是业务输入错误，后两类来自文件系统，错误链应继续向上暴露。

package files

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

func ClassifyReadError(err error) string {
    // 先判断自定义输入错误，再判断标准库的哨兵错误。
    if errors.Is(err, ErrInvalidName) {
        return "invalid-name"
    }
    if errors.Is(err, fs.ErrNotExist) {
        return "not-found"
    }
    if errors.Is(err, fs.ErrPermission) {
        return "permission-denied"
    }
    if err != nil {
        return "read-failed"
    }
    return "ok"
}

func WrapReadError(name string, err error) error {
    // %w 保留底层 PathError，调用方无需匹配错误字符串。
    if err == nil {
        return nil
    }
    return fmt.Errorf("read %q: %w", name, err)
}

fs.PathError 还记录了操作名、路径和底层原因。服务层可以把 invalid-name 映射为参数错误，把 not-found 映射为资源不存在；不要因为对外返回统一错误码，就在存储层过早丢掉错误链。

从 filepath.Join 迁移时的回归清单

迁移旧代码时，我会先找出所有“用户输入 + 根目录”的拼接点，再逐个替换为固定 fs.FS。下面这张表适合作为代码评审的最小清单：

最后保留两组测试：一组只测 ValidPath 的输入表，另一组用 testing/fstest.MapFS 测读取函数如何区分错误。这样可以把路径语法回归和实际存储行为分开，后续替换文件系统实现时也不必改业务测试。

结论：先限制命名空间，再选择根目录边界

fs.ValidPath 适合做用户文件名进入 io/fs 前的第一道语法门；os.DirFS 和 fs.Sub 负责把业务读取限制在一个明确的文件系统视图内；错误链和符号链接策略则决定了工程方案是否完整。三者要配合使用，不能用其中一个函数替代全部安全边界。

相关问题

• fs.ValidPath 会自动处理 Windows 反斜杠吗？ 不会把反斜杠当作 io/fs 分隔符；它在 fs 命名空间里可以是普通字符，具体 FS 实现不能再把它解释成分隔符。
• fs.Sub 会检查子目录是否存在吗？ 不会预先检查；真正读取或打开时才会得到对应错误。
• 只用 filepath.Clean 可以替代 ValidPath 吗？ 不建议。Clean 会规范化操作系统路径，而 ValidPath 是 FS.Open 约定的输入判断，两者语义不同。

参考资料：https://pkg.go.dev/io/fs#ValidPath；https://pkg.go.dev/io/fs#Sub；https://pkg.go.dev/io/fs#FS。