Go 怎样判断归档内路径是否安全合法

处理归档条目名、embed.FS 或其他 io/fs.FS 时，判断路径格式可以直接使用 io/fs.ValidPath。它接受 UTF-8、未以斜杠开头或结尾、由斜杠分隔的相对路径；单独的 . 是根目录特例，而空字符串、..、重复斜杠和包含点元素的路径会被判为无效。

官方文档：https://pkg.go.dev/io/fs#ValidPath

ValidPath 只回答“这个名字是否符合 io/fs 的路径格式”。它不回答文件是否存在，也不替代业务权限、归档格式校验或宿主机路径隔离。

• 格式层：先用 fs.ValidPath(name) 拦截不符合 FS 约定的名称。
• 读取层：格式通过后，再让 fs.FS.Open 或 fs.ReadFile 判断对象是否存在、能否读取。
• 业务层：对归档条目、权限、大小和符号链接等规则继续单独做判断，不把一个布尔值当成全部安全结论。

先用固定样例建立判断基线

写归档读取代码时，最容易混淆的是“看起来像路径”和“符合 io/fs 路径名约定”。可以先准备 7 个固定样例：.、docs/readme.md、空字符串、/docs、docs/、docs//readme.md、docs/./readme.md 和 docs/../secret。前两个是格式合法的代表，其余用于覆盖首尾斜杠、空元素和点元素边界。

用 io/fs.ValidPath 判断归档条目名

归档读取函数通常只需要在真正访问文件系统前增加一层格式判断。下面的示例把判断结果分成“格式非法”和“格式合法但尚未读取”，避免把 ValidPath 的返回值误写成文件存在性结论。

package main

import (
    "fmt"
    "io/fs"
)

func classifyPath(name string) string {
    // ValidPath 只检查 io/fs 规定的路径格式，不检查文件是否存在。
    if !fs.ValidPath(name) {
        return "格式非法"
    }
    // 通过格式层后，仍要交给具体 FS 执行打开或读取。
    return "格式合法，等待 FS.Open 或 fs.ReadFile"
}

func main() {
    // 固定样例用于说明边界，不代表某个真实归档的运行输出。
    samples := []string{".", "docs/readme.md", "", "/docs", "docs/../secret"}
    for _, name := range samples {
        fmt.Printf("%q: %s\n", name, classifyPath(name))
    }
}

这里的基线指标不是耗时，而是输入类别覆盖：根目录、普通层级、空名称、首部斜杠和父目录元素各有一个样例。这样做的好处是，代码评审时可以直接追问“这个条目名属于哪一类”，而不是只看一个模糊的正则表达式。

格式合法不等于文件真实存在

io/fs.FS 的 Open 接口接收合法的 FS 路径名，但具体文件系统仍可能返回不存在、权限或其他读取错误。对归档条目来说，正确顺序是先判断名称格式，再调用读取接口，并保留错误语义。

package archive

import (
    "fmt"
    "io/fs"
)

func readEntry(fsys fs.FS, name string) ([]byte, error) {
    // 在进入具体 FS 前拒绝不符合路径约定的条目名。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("归档条目名格式非法: %q", name)
    }

    // fs.ReadFile 负责向 FS 请求内容；格式合法不代表对象一定存在。
    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        // 保留底层错误，调用方才能区分不存在、权限或其他读取失败。
        return nil, fmt.Errorf("读取归档条目 %q: %w", name, err)
    }
    return data, nil
}

如果底层实现遵循 io/fs 的约定，非法名称通常会对应 ErrInvalid，不存在的名称则可能对应 ErrNotExist。业务代码不应仅凭 ValidPath == true 就返回“读取成功”，而应继续处理 fs.ReadFile 的错误。

不要把 ValidPath 当成完整安全策略

这个 API 的价值是统一 io/fs 的路径名格式，尤其适合归档、嵌入资源和抽象文件系统。它不负责验证归档条目的大小、压缩比、权限、业务目录白名单，也不替你决定是否允许读取某个对象。

还要记住一个容易忽略的事实：io/fs 路径在所有系统上都使用斜杠，反斜杠和冒号可以作为普通字符被接受，但 FS 实现不能把它们擅自当成路径分隔符。若目标是本地磁盘路径，应该单独采用本地路径 API 的规则，不要把两套路径模型混写。

常见问题

fs.ValidPath(".") 为什么是 true？

. 是 io/fs 约定的根目录名称。它不是普通的点元素；但 docs/./readme.md 含有点元素，因此不属于同一特例。

路径中可以使用反斜杠吗？

从 ValidPath 的格式判断看，反斜杠不是 io/fs 的分隔符，因此可能被接受为元素内容。真正的 FS 实现不能再把它解释成另一层分隔；业务若要限制字符，应增加自己的规则。

验证通过后还需要调用什么？

需要调用具体的 FS.Open、fs.ReadFile 或其他读取接口，并处理不存在、权限和读取失败。格式合法只是进入文件系统操作前的一个边界。

归档路径的判断可以收束为一句话：先用 io/fs.ValidPath 判断名称格式，再让具体 FS 判断对象和读取结果，最后由业务规则决定是否允许继续使用。