Go os.DirFS 怎样读取受限根目录中的文件

如果程序只需要把一个固定目录当作文件树读取，os.DirFS 的写法很短：先把绝对目录转换为 fs.FS，再用 fs.ReadFile 或 fs.Open 处理相对路径。需要先说清边界：fs.ValidPath 能拦住绝对路径、空路径和 .. 片段，但 os.DirFS 不会阻止目录内的符号链接指向根目录外。如果文件名来自用户或归档包，Go 1.24 及以上应优先使用 os.OpenRoot。

官方地址：https://pkg.go.dev/os#DirFS

本文使用“资产—攻击路径—控制措施”的顺序，把“能读取”与“不会越界”拆开说明。

先用 os.DirFS 建立目录访问边界

os.DirFS(rootDir) 返回一个 fs.FS，后续传给 fs.ReadFile 的名称应是以斜杠分隔的相对路径，例如 config/app.yaml。这里的根目录是程序选择的目录，读取接口不需要反复拼接系统路径。

package main

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

func readUnderDir(rootDir, name string) ([]byte, error) {
    // 空目录会让 os.DirFS 直接报错，先把配置问题说清楚。
    if rootDir == "" {
        return nil, fmt.Errorf("root directory is empty")
    }

    // io/fs 统一使用斜杠路径，拒绝绝对路径和父目录跳转。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid relative path %q", name)
    }

    // DirFS 只负责建立文件树视图，不会复制或锁定目录内容。
    publicFS := os.DirFS(rootDir)
    data, err := fs.ReadFile(publicFS, name)
    if err != nil {
        // 保留底层错误，调用方仍可用 errors.Is 判断不存在或权限问题。
        return nil, fmt.Errorf("read %q: %w", name, err)
    }
    return data, nil
}

这个最小版本适合读取应用自己管理的静态资源。fs.ReadFile 会负责打开、读取并关闭文件；如果改成手动 fs.Open，就必须在成功打开后调用 Close。

fs.ValidPath 能挡住什么，不能挡住什么

fs.ValidPath 的规则是路径不能为空，不能以斜杠开头或结尾，也不能包含 .、.. 这类独立路径元素。它解决的是“调用者传入的名字是否符合 io/fs 约定”，不是“操作系统解析后一定留在目录内”。

func validAssetName(name string) bool {
    // 这些输入不是 io/fs 允许的 Open 名称。
    if !fs.ValidPath(name) {
        return false
    }
    // 业务层可以继续限制后缀，避免资源入口变成任意文件读取器。
    return strings.HasSuffix(name, ".yaml") || strings.HasSuffix(name, ".json")
}

例如目录中存在 public/link，它是指向根目录外的符号链接，那么 os.DirFS("public").Open("link") 仍可能跟随这个链接。官方文档明确说明，DirFS 不是 chroot 式安全机制；同样，fs.Sub 也不会改变这个事实。

因此要把风险分成两类：固定目录中的可信资源，用 DirFS 加路径规则即可；不可信文件名、解压目录或可被其他进程改写的目录，则需要能抵抗符号链接和路径竞态的根目录 API。

不可信文件名改用 os.OpenRoot

Go 1.24 新增的 os.OpenRoot 会返回一个绑定目录的 *os.Root，再通过 Root.FS() 暴露 fs.FS。这个根对象会拒绝通过 .. 或越界符号链接离开根目录。

func readUntrustedName(rootDir, name string) ([]byte, error) {
    // OpenRoot 将目录句柄绑定到目标根，适合处理外部传入的文件名。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return nil, fmt.Errorf("open root: %w", err)
    }
    // Root 持有系统资源，所有返回路径都要经过关闭。
    defer root.Close()

    // 先保留 io/fs 的名称约束，再交给 Root.FS 做目录逃逸防护。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid relative path %q", name)
    }
    data, err := fs.ReadFile(root.FS(), name)
    if err != nil {
        return nil, fmt.Errorf("read inside root: %w", err)
    }
    return data, nil
}

如果只想打开一个文件，也可以考虑 os.OpenInRoot(rootDir, name)。选择哪种方式取决于后续是否还要复用这个根目录：一次性读取用 OpenInRoot 更直接，需要连续操作多个文件则保留 *os.Root 更清楚。

参数与风险速查

最后检查三点：目录参数不能是空字符串；传给 io/fs 的名称使用斜杠而不是系统路径拼接；凡是调用 os.OpenRoot 成功的分支都要关闭 Root。不要把“通过了 ValidPath”当作完整的安全证明。

相关问题

os.DirFS 能代替 chroot 吗？

不能。它提供的是相对文件树视图，不会阻止根目录内的符号链接指向外部。

fs.ValidPath 为什么不接受 Windows 反斜杠路径？

io/fs 的路径协议统一使用斜杠。反斜杠可以作为普通字符存在，但实现不能把它当成分隔符。

什么时候还应该用 os.DirFS？

当目录内容可信、目标是统一接入 io/fs API，且不需要把它当作安全沙箱时，os.DirFS 仍然是清晰的选择。