Go io/fs.ValidPath 的相对路径校验与目录边界

做嵌入式资源、归档读取或模板文件服务时，fs.FS.Open 的名称不是操作系统路径。最稳妥的入口处理是先调用 io/fs.ValidPath：它接受以 . 表示根目录、以斜杠分隔的相对路径，拒绝空串、绝对路径、重复斜杠、. 和 .. 路径段。通过校验后再交给 FS 实现，文章里只讨论这个命名契约，不把它扩展成权限或越界安全机制。

把 ValidPath 放在 FS.Open 的入口

fs.FS 要求 Open 接收 slash 分隔的名称，接口实现应拒绝不满足 ValidPath 的输入。它和 filepath.Clean 的目标不同：后者会尝试把路径整理成宿主机路径，而 ValidPath 只回答“这个名称是否符合 fs.FS 的调用约定”。

package main

import (
    "fmt"
    "io/fs"
)

func openName(fsys fs.FS, name string) ([]byte, error) {
    // 先校验 FS 名称，避免把空串或父级路径交给实现层解释。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid fs name %q", name)
    }
    // 通过校验后才调用 Open；实现仍需按 FS 契约返回错误。
    file, err := fsys.Open(name)
    if err != nil {
        return nil, err
    }
    defer file.Close() // 读取结束后释放文件句柄。
    return fs.ReadFile(fsys, name)
}

示例中的前置判断适合把错误尽早归类；如果你正在实现自定义 FS，仍应在自己的 Open 方法中重复这个边界检查，因为调用方可能绕过包装函数。

掌握根路径、空串和斜杠规则

最容易误判的是 .。它是合法的根名称，而空串不是；x/y 是普通的相对层级，x/ 末尾斜杠、x//y 重复斜杠、x/./y 和 x/../y 都应拒绝。不要先调用清理函数再判断，否则可能把原始输入的错误隐藏掉。

处理 Windows 字符与跨平台边界

这个规则是跨平台的：路径段之间固定用正斜杠。反斜杠和冒号本身可以出现在一个名称中，例如 report\\2026 仍可能是一个包含反斜杠字符的单段名称；它们不应被 FS 实现擅自改解释为 Windows 分隔符或盘符。若业务输入来自用户文件路径，先定义“转换为 fs 名称”的明确协议，再调用 ValidPath，不要把两套路径语义混用。

自定义 FS 的实现检查清单

1. 在 Open 内检查 fs.ValidPath(name)，非法输入返回带有 ErrInvalid 语义的 PathError。
2. 内部映射时只把 / 当作 fs 名称分隔符；反斜杠、冒号不可暗中变成宿主机路径语法。
3. 需要访问宿主机目录时，单独设计映射和权限边界；ValidPath 不是 chroot，也不会替你阻断符号链接带来的外部访问。
4. 用 .、普通多级名称、空串、绝对路径、重复斜杠和 .. 做表格化测试。

相关问题

ValidPath 能替代 filepath.Clean 吗？

不能。前者检查 io/fs 名称契约，后者处理宿主机路径清理；两者输入语义不同。

为什么 . 合法而空串非法？

. 是 fs.FS 用来表示根目录的名称，空串没有可识别的路径段。

通过 ValidPath 就一定没有目录越界吗？

不一定。它拒绝 .. 等名称，但自定义映射、符号链接和权限仍需单独设计。