Go io/fs.ValidPath 如何判断嵌套路径：点号规则、分隔符边界与归档校验

把用户上传的归档条目交给 io/fs 之前，最容易漏掉的不是普通的 ../，而是空路径、开头斜杠、连续斜杠和“看起来像当前目录”的点号。fs.ValidPath 适合做这一层很窄、很明确的路径格式检查：它接受当前目录下的相对 slash-separated 路径，同时拒绝会改变层级语义的写法。

需要校验嵌套文件名时，先用 fs.ValidPath 判断路径格式；它不是权限系统，也不会替你判断文件是否存在。

先看清故障：合法文件名为什么会被误判

这类问题通常出现在归档导入或内存文件系统遍历中。业务代码把用户输入按操作系统路径处理，随后又把它交给只认 slash-separated 路径的 fs.FS，两套规则叠在一起，最终表现为“某些目录能读，某些目录读不到”。

这里先把边界缩小到一个函数和一组输入。下面的程序不创建文件，也不访问磁盘，只打印格式判断结果：

package main

import (
    "fmt"
    "io/fs"
)

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

    for _, path := range paths {
        fmt.Printf("%-22q valid=%v%n", path, fs.ValidPath(path))
    }
}

运行后，只有 docs/readme.md 会稳定通过。这个结果说明校验器关心的是路径的语法边界，而不是文件系统里有没有同名文件。

四类输入边界决定了判断结果

普通嵌套路径可以保留层级

docs/readme.md 由两个非空路径元素组成，斜杠只负责分隔目录层级。多级路径同理，例如 assets/icons/menu-icon。不要为了“更安全”把所有斜杠替换成下划线，否则你会丢失 fs.FS 的目录语义。

点号元素不是普通文件名

. 和 .. 会改变路径解析时的当前位置，所以 ./docs/readme.md、docs/../secret.txt 都不应作为 fs.FS.Open 的标准输入。单独的 . 也会被拒绝；需要表达根目录时，应使用具体 FS API 的约定，而不是把点号混入外部路径。

斜杠只能做分隔符

开头斜杠表示绝对路径，结尾斜杠通常表示目录而不是一个文件名，连续斜杠则会产生空的路径元素。因此 /docs/a.txt、docs/a.txt/ 和 docs//a.txt 都不通过。

空字符串不是根目录别名

空字符串看起来像“没有指定文件”，但 fs.FS.Open 需要的是一个明确的相对路径。把它当根目录或默认文件，往往会让上层业务在导入流程里出现隐式分支；先拒绝，再让调用方明确选择目录或文件，排查成本更低。

把校验放在归档条目进入 FS 之前

如果归档格式提供了条目名称，校验点应该在创建文件、写入内存 FS 或拼接目标目录之前。校验通过只意味着路径格式合规，后面仍要检查条目类型、大小、重复名称以及业务权限。

func acceptEntry(name string, size int64) error {
    if !fs.ValidPath(name) {
        return fmt.Errorf("invalid archive entry path %q", name)
    }
    if size  64

注意错误信息可以记录原始条目名，但不要把这一步误写成“已经安全”。它没有检查软链接语义，也没有授予读取权限；它只完成了 io/fs 这一层要求的路径形状检查。

线上排查时先确认调用链

遇到“同一个文件在本地能打开、导入后打不开”，先记录三项：原始条目名、fs.ValidPath 结果、实际传给 Open 的字符串。尤其检查是否在中间调用了 filepath.Clean 或手工补了前导斜杠。前者可能把原始输入规范化成另一条路径，后者会直接改变 FS API 所需的相对路径语义。

复现时建议同时保留一组应该通过和应该拒绝的样例，避免修复只覆盖了报错样本：

func TestArchiveEntryPath(t *testing.T) {
    tests := map[string]bool{
        "readme.md":          true,
        "docs/readme.md":     true,
        "":                   false,
        ".":                  false,
        "./readme.md":        false,
        "docs/../readme.md":  false,
        "docs//readme.md":    false,
        "/readme.md":         false,
    }

    for path, want := range tests {
        if got := fs.ValidPath(path); got != want {
            t.Errorf("ValidPath(%q)=%v, want %v", path, got, want)
        }
    }
}

常见问题

fs.ValidPath 会检查文件是否存在吗？

不会。它只检查 slash-separated 相对路径的格式；文件是否存在要由具体的 fs.FS 和 Open 调用确认。

Windows 路径能直接传给它吗？

不要直接把反斜杠路径当作通用 FS 路径。io/fs 的路径约定使用斜杠；跨平台输入应先在边界层转换并明确记录转换规则。

通过校验就等于没有目录穿越风险吗？

不能这样推断。ValidPath 拒绝点号元素，但权限、软链接、资源大小、重复条目和业务授权仍需要单独设计和验证。

收尾检查

把 fs.ValidPath 当成“路径格式门”，而不是完整安全方案：先拒绝空路径、点号元素和异常斜杠，再让具体文件系统判断存在性，最后补上条目大小、类型和授权检查。这样既能保留合法的嵌套目录，也能让归档导入的失败原因落在可复现的边界上。