Go fs.ValidPath 怎样判断相对路径是否合法

判断一个名字能否用于 Go 的 io/fs 接口，直接调用 fs.ValidPath(name)。它要求 UTF-8、正斜杠分隔、没有空路径元素以及 .、.. 元素；单独的 "." 是表示文件系统根目录的例外。它不是任意操作系统相对路径的合法性判断，也不检查文件是否存在。

官方文档地址：https://pkg.go.dev/io/fs

我先给路径选一种语法

设计资源读取入口时，我会先问调用方传的是“资源名称”还是“本机文件路径”。比如资源清单里的 themes/night.css，适合当作 FS 名称；用户从文件选择器得到的本机路径，则不应该直接套入同一份约定。两者都叫路径，却不属于同一个命名空间。

本文不介绍新版本语法，而是把含糊的“相对路径”接口收窄为明确的 io/fs 名称契约。这个取舍的好处是：同一资源清单不必随宿主系统改变斜杠。代价也很清楚，不能再默默接纳任意本地路径。

我不会只用“不是绝对路径”来代表合法。例如 assets/../readme.txt 即使看起来相对，也不符合 FS 名称规则。也不会用“包含两个点”判断父目录元素：release..txt 中的点属于普通文件名，不等同于一个完整的 .. 元素。

ValidPath 判断的是原始名称，不替你修正它

这里把输入称作原始名称，其中的正斜杠划分路径元素，字符串编码接受UTF-8 条件约束。根目录特例仅指整个名称恰好为一个点。这些条件共同组成FS 名称规则，最终由 ValidPath 判定检查。

表格是依据语法作出的说明，不是本地测试输出。ValidPath 是判断，不是规范化；它不修改参数，也不会清理多余斜杠。假设业务要求拒绝原始名称中的父目录元素，我会先判断原始字符串，而不是先调用 Clean 消除元素以后再说“原始输入合法”。

这里还有个容易产生分歧的地方：反斜杠和冒号可以作为 FS 名称中的普通字符被接受，但 FS 实现不能把它们偷偷解释成路径元素分隔符。我倾向于在要求跨系统迁移的资源清单中进一步拒绝这两类字符；那是业务政策，不是 ValidPath 的内置规则。

把名称检查和 Open 的错误分开

下面是一份原创封装示例：让调用方传入已经选择好的非 nil fs.FS，封装只负责原始名称和两条资源业务规则。它不读取整个文件，也不承诺目标一定是普通文件。

package assetname

import (
    "io/fs"
    "strings"
)

// OpenAsset 接收未清理的 FS 名称；fsys 必须由调用方提供。
func OpenAsset(fsys fs.FS, name string) (fs.File, error) {
    if !fs.ValidPath(name) {
        // 语法不合法时不调用底层文件系统。
        return nil, &fs.PathError{Op: "open-asset", Path: name, Err: fs.ErrInvalid}
    }
    // 本业务只读具体资源，拒绝根目录和两类非可移植字符。
    if name == "." || strings.ContainsAny(name, "\\:") {
        return nil, &fs.PathError{Op: "open-asset", Path: name, Err: fs.ErrInvalid}
    }
    // 存在性、权限及具体实现支持范围由实际 Open 决定。
    return fsys.Open(name)
}

代码中的字符串 "\\:" 在 Go 源码里表示匹配反斜杠与冒号，不能误写成无效转义。两个判断故意分开：第一处是语法检查，第二处是业务命名规则。这样维护者不会以为“根目录不是合法 FS 名称”，也不会把业务禁止字符写进对标准库的描述。

之后的底层 Open才会接触具体 FS，实现可以是内存资源、嵌入资源或目录映射。它可能返回文件句柄，也可能返回访问错误。上面的封装不把“找不到文件”“权限不足”或其他实现错误全部改写为路径格式错误。

调用者成功拿到句柄后负责 Close；若 Close 的错误与业务结果相关，应在返回路径中处理，不能默认忽略。需要读取普通文件、限制读取大小或只允许某个资源目录时，再增加对应策略。仅凭名字通过，不能认定句柄的类型和内容都符合业务要求。

需要本地路径时，转换也可能失败

对于直接交给 fs.FS.Open 的名称，不要先转成操作系统分隔符。只有确实要跨到操作系统路径接口时，才考虑显式转换。在 Go 1.23 及更新版本中，filepath.Localize 可以把符合 FS 语法的名称转成本地路径，并在无法表示时返回错误。

路径工具官方文档：https://pkg.go.dev/path/filepath

// 此片段放在已导入 path/filepath 的函数内；需要 Go 1.23 或更新版本。
localName, err := filepath.Localize(name)
if err != nil {
    // 不能表示为本地路径时保留错误，不强行替换分隔符。
    return "", err
}
return localName, nil

这个片段假设外层函数接收 name 并返回 (string, error)，不是独立程序。Localize 本身就要求并检查有效 FS 路径；显式先调用 ValidPath 的价值在于区分接口错误，不是让转换结果获得额外权限。

例如一个含反斜杠的 FS 名称，在 Windows 上不能按“文件名里的普通反斜杠”表示，转换会失败。相反，简单替换斜杠的 FromSlash 不承担相同的输入合法性保证。我的选择是保留转换错误，不通过替换、截断或清理把一个名字悄悄换成另一个。

旧工具链没有 Localize 时，需要按目标系统自行定义转换政策，或者让资源访问一直停留在 FS 接口中。不要为了写一个兼容分支就宣称 ValidPath + FromSlash 与 Localize 在所有平台上等价。

合法名称不等于文件存在或访问获准

我会把这条界限放进接口注释：ValidPath 不做文件系统访问，不检查存在性、权限、业务授权，也不处理符号链接目标。os.DirFS 的官方文档也明确说明，它不是针对任意目录内容的通用隔离机制。名称语法通过，不能据此承诺实际访问一定留在某个目录树中。

这篇示例的目标是让资源名称契约清楚，不是提供完整的沙箱实现。涉及不可信目录、链接或多用户访问时，应独立设计受限访问与授权机制；不要把一个布尔值扩大成对实际文件访问的安全保证。

常见问题

为什么单独的点通过，带点的中间目录却不通过？根目录是单独约定的表示，不意味着可以在路径内部任意插入点元素。业务不允许根目录时，就像示例一样额外拒绝。

带百分号的名字需要先解码吗？ValidPath 不负责 URL 解码。接口到底接收 URL 路径还是已经解码的 FS 名称，应由上层定义；不要检查一种表示，却用另一种表示访问。

合法路径为什么仍然打不开？语法正确与资源可访问是不同条件。保留 Open 返回错误，根据具体实现处理，不要循环 Clean 后重试同一个名字。

文件名中能包含空格或中文吗？不能因为这些字符本身就判断违反 FS 语法；实际实现支持范围和业务命名规则仍可能更窄。

对我来说，最值得保留的规则只有一句：先约定路径属于哪个接口，再检查那个接口的原始名称。FS 名称用 ValidPath，本地表示按需转换，真实访问结果交给 Open；三者不能互相替代。

参考：io/fs 路径名称与 ValidPath；filepath.Localize；os.DirFS 的访问范围说明。