Go fs.Sub 后访问根目录文件失败怎么办

我在把配置目录交给一个只认识 fs.FS 的函数时，最容易踩到的坑不是文件真的丢了，而是把 fs.Sub 返回的文件系统继续当成原来的目录来用。结论很简单：如果 sub, _ := fs.Sub(fsys, "config")，那么 config 已经成为 sub 的根，根目录本身用 "." 表示，根下的 app.yaml 直接用 "app.yaml" 读取。

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

fs.Sub 返回的根目录到底在哪里

fs.Sub(fsys, "config") 返回的是以 config 为起点的新视图。对新视图调用 Open("app.yaml")，等价于在原文件系统中打开 config/app.yaml；此时再写 config/app.yaml，就会多拼一层目录。

根目录不是一个需要重新拼接的物理路径，而是新 FS 视图中的逻辑位置。需要列根目录时可以用 "."；需要读取根下文件时，直接从文件名开始。

先用最小例子固定路径写法

下面的例子把 project/config 映射成 sub。示例同时读取根目录文件和子目录文件，便于把“根”和“原目录前缀”区分开。

package main

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

func loadConfig() error {
    // 原文件系统的根是 project，config 会成为 sub 的新根。
    base := os.DirFS("project")
    sub, err := fs.Sub(base, "config")
    if err != nil {
        return fmt.Errorf("创建子文件系统失败: %w", err)
    }

    // 根目录下的 app.yaml 不再带 config 前缀。
    data, err := fs.ReadFile(sub, "app.yaml")
    if err != nil {
        // 合法路径但找不到文件，通常应从 ErrNotExist 方向排查。
        if errors.Is(err, fs.ErrNotExist) {
            return fmt.Errorf("配置文件不存在: %w", err)
        }
        return fmt.Errorf("读取配置失败: %w", err)
    }
    fmt.Printf("读取到 %d 字节配置\n", len(data))

    // . 表示 sub 的根，适合用于列出根目录内容。
    entries, err := fs.ReadDir(sub, ".")
    if err != nil {
        return fmt.Errorf("列出配置目录失败: %w", err)
    }
    for _, entry := range entries {
        // 只展示名称，避免把原文件系统前缀重新带入后续调用。
        fmt.Println(entry.Name())
    }
    return nil
}

这里的关键不是 ReadFile 本身，而是调用它时的第二个参数。sub 已经站在 config 目录上，app.yaml 才是它根下的文件；config/app.yaml 会被解释为子树里的下一层路径。

为什么有些写法会变成 ErrInvalid

io/fs 的路径不是操作系统原生路径。fs.ValidPath 要求路径使用斜杠分隔，允许 "." 表示根，但不接受空路径、绝对路径，以及包含 "." 或 ".." 路径段的写法。因此把常见的文件系统拼接习惯原样搬过来，就可能在真正打开文件前失败。

package main

import (
    "fmt"
    "io/fs"
)

func inspectPaths() {
    paths := []string{".", "app.yaml", "assets/logo.svg", "/app.yaml", "./app.yaml", "../app.yaml", "assets//logo.svg"}
    for _, path := range paths {
        // 先检查路径契约，可以把 ErrInvalid 与文件不存在区分开。
        fmt.Printf("%q valid=%t\n", path, fs.ValidPath(path))
    }
}

排查时可以把错误分成两类：

目录参数不存在时，不要误判为立即失败

fs.Sub 会校验目录参数的路径形式，但不会提前检查这个目录当前是否存在。也就是说，创建 sub 成功，只说明映射关系建立了；真正调用 ReadFile、ReadDir 或 Open 时，才会暴露目录或文件不存在的问题。

因此初始化阶段适合检查 fs.Sub 的错误，业务读取阶段再根据 fs.ErrNotExist 决定是使用默认配置、返回 404，还是直接让启动失败。不要把所有错误都包装成“路径非法”，否则定位方向会被带偏。

还要留意 fs.Sub 的安全边界

fs.Sub 是路径视图，不是操作系统级的 chroot。官方文档特别提醒，使用 os.DirFS 时，子目录里的符号链接仍可能指向目录树之外；Sub 不会改变这个事实。文章中的修复只针对“根路径写错”与“ValidPath 不满足”，不能把它当成额外的安全隔离方案。

如果需求是限制访问范围，应根据当前 Go 版本和部署环境选择适合的目录约束机制，并单独评估符号链接、权限和进程边界。不要因为 sub 只暴露了一个目录名，就推断底层访问已经被完全封闭。

常见问题

fs.Sub 后读取根目录下的文件要写成 "." 加文件名吗？

不需要。根目录用 fs.ReadDir(sub, ".") 表示；根下文件直接使用 fs.ReadFile(sub, "app.yaml")。

为什么写 config/app.yaml 反而找不到文件？

因为 config 已经是 sub 的根。继续拼接它会把查找范围推进到 config/config/app.yaml 的逻辑位置。

Windows 路径能不能传反斜杠？

io/fs 的路径统一使用斜杠分隔。业务代码应传 assets/logo.svg 这类 slash 路径，不要把本地文件系统的反斜杠习惯带入 FS.Open。