Go fs.Sub 为什么会拒绝带点点的路径

fs.Sub 拒绝带有 .. 的路径，不是因为它不会“化简”路径，而是因为它压根不接受这种名字。io/fs 把路径定义为与平台无关的逻辑名字：使用斜杠分隔、不能以斜杠开头、不能出现空元素，也不能出现 . 或 .. 元素；唯一的例外是单独的 .，它表示文件系统根。

我第一次遇到这个错误时，也下意识想在调用前加一次 path.Clean。后来对照源码才发现，这样做反而绕开了 API 用来暴露配置错误的边界。正确做法通常不是清理 ..，而是重新选择文件系统的根。

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

先看结论：点点不是可清理的输入

fs.Sub(fsys, dir) 一开始就调用 fs.ValidPath(dir)。校验失败时返回 *fs.PathError，其中操作名是 sub，底层错误是 fs.ErrInvalid。因此 ../templates、assets/../templates 和 assets/./templates 都不会被折叠成别的名字。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "testing/fstest"
)

func main() {
    // MapFS 的键已经位于逻辑根内，Sub 只接受根内的有效名字。
    files := fstest.MapFS{"assets/index.html": {Data: []byte("ok")}}

    _, err := fs.Sub(files, "assets/../assets")
    // 含有 .. 元素，errors.Is 会识别到底层的 ErrInvalid。
    fmt.Println(errors.Is(err, fs.ErrInvalid))
}

使用场景：为什么人会自然写出点点

常见场景是项目里有 web/templates 和 web/static，某段代码已经拿到了 web/static 对应的文件系统，却又想通过 ../templates 回到兄弟目录。在操作系统路径里，这个写法很自然；在 io/fs 里，它说明“当前文件系统根选窄了”。

fs.FS 的调用者只能看见逻辑根以内的名字。既然兄弟目录不在当前根内，就应该把根提升到共同父目录，或者分别创建两个文件系统，而不是从子树内部向上穿越。这个限制也让 embed.FS、ZIP 文件系统和内存文件系统能够共享同一套命名规则。

候选方案一：把文件系统根放对位置

如果资源来自 embed.FS，我通常先嵌入共同父目录，再用合法子路径缩小视图。这样业务代码看到的根正好是它需要的目录，不必知道构建时的上层布局。

package assets

import (
    "embed"
    "io/fs"
)

//go:embed web/*
var bundled embed.FS

func Web() (fs.FS, error) {
    // web 是有效逻辑路径；返回后 index.html 等名字都相对新根解析。
    return fs.Sub(bundled, "web")
}

如果资源来自磁盘，并且某个操作系统目录本来就应该成为逻辑根，可以直接使用 os.DirFS(base)。此后再调用 Open("templates/page.html")，而不是把 base 拼进逻辑名字，也不需要 ..。

候选方案二：根据安全边界选择 API

fs.Sub、os.DirFS 和 os.Root 解决的问题并不完全相同。fs.Sub 是给已有 fs.FS 建立子树视图；os.DirFS 是把一个磁盘目录映射成 fs.FS；os.Root 提供受限于目录树的操作系统文件访问 API，适合需要把符号链接越界也纳入安全边界的场景。

这里有个容易忽略的细节：官方文档明确提醒，fs.Sub(os.DirFS("/"), "prefix") 与 os.DirFS("/prefix") 都不是 chroot。目录里的符号链接仍可能指向文本目录之外。如果你的目标只是统一资源路径，这两种方式够用；如果目标是对不受信任名字建立安全约束，就要把“路径语法有效”和“实际访问不能越界”分开设计。

对比维度：哪些名字有效，哪些一定失败

在 Windows 上也应继续用 / 表达 io/fs 层级。反斜杠可以作为普通字符出现在名字中，但文件系统实现不能把它解释为路径分隔符，所以不要用 filepath.Join 构造 fs.FS 内部名字；需要组合逻辑名字时使用 path.Join，并对外部输入保持显式校验。

推荐选择：保留原始错误并尽早暴露配置问题

路径来自配置时，最好先保留原始值，再把 PathError 中的 Op、Path 和底层错误记录出来。这样能直接看出失败发生在建立子树阶段，而不是后续读取文件阶段。

package subfs

import (
    "errors"
    "fmt"
    "io/fs"
)

func OpenSub(fsys fs.FS, dir string) (fs.FS, error) {
    sub, err := fs.Sub(fsys, dir)
    if err == nil {
        return sub, nil
    }

    var pe *fs.PathError
    // 保留原始配置值，避免 Clean 把错误配置伪装成另一个合法目录。
    if errors.As(err, &pe) && errors.Is(pe.Err, fs.ErrInvalid) {
        return nil, fmt.Errorf("子文件系统目录 %q 不符合 io/fs 规则: %w", dir, err)
    }
    return nil, err
}

还有一点值得单独记住：fs.Sub 创建子文件系统时不会检查 dir 是否真实存在。dir 语法有效但目录不存在时，构造可能成功，直到第一次 Open、ReadFile 或 ReadDir 才暴露底层错误。排查时要先区分“名字无效”和“资源不存在”。

不适用情况与常见误区

• 不要用 path.Clean 接受点点：它会改变调用者表达的目标。若清理后越过你设想的业务边界，日志里还会丢失原始错误意图。
• 不要用 filepath.Clean 处理 io/fs 名字：它遵循本机操作系统规则，而 io/fs 使用平台无关的斜杠规则。
• 不要把 ValidPath 当成存在性检查：它只验证名字格式，不访问底层文件系统。
• 不要把 fs.Sub 当成沙箱：对磁盘文件系统而言，符号链接的实际解析仍要由更强的受限访问机制处理。
• 不要为访问兄弟目录扩大用户输入权限：应该由应用代码选择共同父根，再把固定的有效相对名交给业务逻辑。

决策表：遇到不同根目录需求怎么选

相关问题

为什么单独的点可以，路径里的点却不可以？

单独的 . 是 io/fs 约定的根名字；a/./b 中的点元素没有必要，会造成同一资源出现多种写法，因此被拒绝。

可以先判断 fs.ValidPath，再调用 fs.Sub 吗？

可以用于更早给出业务提示，但仍要处理 fs.Sub 的错误。外部输入还应结合你的允许目录集合判断，不能只靠语法有效。

fs.Sub 会复制文件吗？

不会。若底层实现支持自己的 Sub 方法，调用会委托给它；否则标准库返回一个包装视图，把新根内的名字映射到底层的 dir/name。

最短的判断口诀是什么？

把 io/fs 名字当成“根内资源键”，不要当成可上下漫游的操作系统路径。看到 ..，优先检查根是否选错。