io/fs.ValidPath 校验用户路径的规则

把用户提交的字符串直接传给 fs.FS.Open 之前，很多人会先调用 path.Clean 或 filepath.Clean，再检查结果里有没有 ..。这套写法容易把三件事混在一起：io/fs 名称格式、操作系统路径格式和真实文件系统访问边界。

fs.ValidPath 只负责第一件事。它判断一个字符串能否作为 io/fs.FS.Open 的名称，规则跨平台一致：名称必须是有效 UTF-8、非根路径、使用正斜杠分段；除了单独的 . 可以表示文件系统根目录，每个路径段都不能是空字符串、. 或 ..。它不会读取磁盘，不会解析符号链接，也不会替你做 URL 解码。

ValidPath 的最小规则表

先看一组最小样例。下面的代码不依赖当前操作系统，因此在 Linux、macOS 和 Windows 上，fs.ValidPath 的布尔结果相同。

package main

import (
    "fmt"
    "io/fs"
)

func main() {
    names := []string{
        ".",
        "docs/readme.md",
        "assets/icon.png",
        "",
        "..",
        "/etc/passwd",
        "docs/",
        "a//b",
        "a/./b",
        "a/../b",
    }

    for _, name := range names {
        fmt.Printf("%-20q %v\n", name, fs.ValidPath(name))
    }
}

这意味着“先 Clean 再校验”会改变接口语义。例如 path.Clean("a/../b") 得到 b，随后当然能通过 ValidPath，但调用方原本提交了一个含双点号段的名称。对安全敏感的用户输入，通常应该先按既定编码解码一次，然后直接验证原始名称；不要在验证前悄悄把非法输入改写成另一个合法文件。

一个可复用的文件名校验函数

. 对 fs.FS 是合法根目录，但“下载单个文件”“读取头像”这类接口通常不应接受根目录。因此业务层要在 ValidPath 之上再加一条约束。

package safeopen

import (
    "fmt"
    "io/fs"
)

func FileName(name string) (string, error) {
    if !fs.ValidPath(name) {
        return "", fmt.Errorf("无效的 io/fs 名称 %q: %w", name, fs.ErrInvalid)
    }
    if name == "." {
        return "", fmt.Errorf("需要文件名，不能使用根目录: %w", fs.ErrInvalid)
    }
    return name, nil
}

func ReadUserFile(fsys fs.FS, input string) ([]byte, error) {
    name, err := FileName(input)
    if err != nil {
        return nil, err
    }

    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        return nil, fmt.Errorf("读取 %q 失败: %w", name, err)
    }
    return data, nil
}

返回时包装 fs.ErrInvalid，上层仍可使用 errors.Is(err, fs.ErrInvalid) 转换成 HTTP 400 或业务参数错误。文件不存在和权限不足则继续由具体的 fs.FS 返回，可分别判断 fs.ErrNotExist 与 fs.ErrPermission。

反斜杠和冒号为什么可能通过

一个经常令人意外的结果是：fs.ValidPath(`a\b`) 和 fs.ValidPath(`C:note.txt`) 可以返回 true。原因是 io/fs 永远只把正斜杠 / 当路径分隔符；反斜杠与冒号只是普通字符。官方要求 FS 实现不能因为运行在 Windows 上，就擅自把这些字符解释成 io/fs 的分隔符。

如果下一步不是调用抽象的 fs.FS，而是要把名称变成本地操作系统路径，应使用 filepath.Localize。它要求输入先满足 fs.ValidPath，再检查当前平台能否表达该名称；例如 Windows 上的 a\b 会被拒绝，因为反斜杠在该平台是分隔符，不能继续保持原来的单段名称语义。

func ToLocalPath(fsName string) (string, error) {
    if !fs.ValidPath(fsName) || fsName == "." {
        return "", fmt.Errorf("无效文件名 %q: %w", fsName, fs.ErrInvalid)
    }

    local, err := filepath.Localize(fsName)
    if err != nil {
        return "", fmt.Errorf("当前系统无法表示 %q: %w", fsName, err)
    }
    return local, nil
}

按路径来源选择工具

HTTP 路径

先明确路由层传进来的是已解码路径还是原始转义文本，只做一次与框架契约一致的解码，然后把固定路由前缀移除。不要先把前导斜杠删掉，再把任意绝对路径伪装成相对名称；也不要反复调用 url.PathUnescape，否则双重编码可能在第二次解码后才变成斜杠或双点号。

最稳妥的接口契约是让业务函数直接接收根内名称，例如 images/a.png，再调用 FileName。URL 路由到根内名称的映射只在适配层完成。

ZIP、TAR 等归档条目

归档条目通常使用正斜杠，适合先用 fs.ValidPath 拒绝绝对名称、空段和双点号段。若随后要写入本地目录，再调用 filepath.Localize；如果目标目录属于安全边界，还需要用受限根目录 API 完成实际写入，而不是只依赖字符串检查。

本地操作系统路径

如果输入契约本来就是当前系统路径，应使用 filepath.IsLocal 做词法判断，而不是 fs.ValidPath。IsLocal 会按当前平台处理绝对路径、双点号和 Windows 保留名。两者没有谁更严格的问题，它们面对的是两种不同的路径语言。

ValidPath 不是文件系统沙箱

ValidPath 不检查文件是否存在、权限是否足够，也不展开符号链接。名称 public/current/config.json 完全符合语法，但如果 current 是指向根目录外的符号链接，单纯的字符串校验无法发现。

os.DirFS 也不是通用的 chroot 替代品。Go 官方文档明确提醒，目录中的符号链接仍可能指向该目录之外。Go 1.24 及更高版本若需要把“只能访问这个目录树”作为安全边界，可以使用 os.OpenRoot 并通过 root.FS() 获得 fs.FS；这样语法校验负责尽早报告参数错误，Root 负责实际访问时限制越界。

func ReadFromRoot(root *os.Root, input string) ([]byte, error) {
    name, err := FileName(input)
    if err != nil {
        return nil, err
    }

    data, err := fs.ReadFile(root.FS(), name)
    if err != nil {
        return nil, fmt.Errorf("受限目录读取 %q 失败: %w", name, err)
    }
    return data, nil
}

这里的分工很清楚：fs.ValidPath 保证参数符合 io/fs 语法；os.Root 约束真实文件操作；业务层继续限制文件类型、大小、扩展名和授权范围。任何一层都不应冒充另外两层。

容易踩坑的四种写法

1. 用字符串包含判断拦截 ..：会误伤 report..txt，却没有表达路径段语义。让 ValidPath 判断段结构。
2. 验证前调用 Clean：可能把本应拒绝的输入改写成另一条合法路径。需要规范化显示时，先验证并保留原始审计值。
3. 把 ValidPath 当 Windows 路径验证器：它不会把反斜杠视为分隔符。本地路径使用 Localize 或 IsLocal。
4. 通过验证后直接拼接宿主目录：语法有效不等于符号链接安全。安全边界要在实际文件操作时执行。

完整测试表

最后给校验函数补一组表驱动测试，把边界固定下来。业务如果允许目录，就单独测试 .；如果只允许文件，则像这里一样明确拒绝。

func TestFileName(t *testing.T) {
    tests := []struct {
        name string
        ok   bool
    }{
        {"readme.md", true},
        {"docs/readme.md", true},
        {".", false},
        {"", false},
        {"../secret", false},
        {"a/../secret", false},
        {"/absolute", false},
        {"a//b", false},
        {"a/./b", false},
        {"目录/说明.txt", true},
        {string([]byte{0xff}), false},
    }

    for _, tt := range tests {
        t.Run(fmt.Sprintf("%q", tt.name), func(t *testing.T) {
            _, err := FileName(tt.name)
            if (err == nil) != tt.ok {
                t.Fatalf("FileName(%q) err=%v, want ok=%v", tt.name, err, tt.ok)
            }
        })
    }
}

判断用户路径时，先问“下一层 API 使用哪种路径语言”。传给 fs.FS 的名称用 fs.ValidPath；从 io/fs 名称转换成本地路径用 filepath.Localize；本来就是本地路径则用 filepath.IsLocal；真实目录边界再交给 os.Root 等访问机制。把这四个职责拆开，代码会比堆叠清理函数更容易审计。

参考资料

• Go 标准库：io/fs.ValidPath
• Go 源码：io/fs/fs.go
• Go 标准库：filepath.Localize
• Go 标准库：filepath.IsLocal
• Go 标准库：os.Root