Go os.DirFS 怎样把本地目录限制为文件系统根目录

在静态资源、模板或归档读取代码里，经常需要把一个本地目录交给只认识 fs.FS 的函数。os.DirFS 的作用是把目录包装成文件系统接口，让调用方用相对的 slash 路径打开文件；但它不是 chroot，也不会自动阻止目录中的符号链接指向外部。

如果目标是“让代码以某个目录为逻辑根”而不是“建立强安全隔离”，可以用 os.DirFS；如果必须防止符号链接越出目录树，应改用 os.Root.FS。

官方文档：https://pkg.go.dev/os#DirFS

os.DirFS 把本地目录包装成 fs.FS

os.DirFS(dir) 接收一个非空目录字符串，返回一个实现了 fs.FS 的值。之后的 Open("assets/app.css") 会以这个目录作为前缀，而不是要求调用方反复拼接绝对路径。

package main

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

func main() {
    // 目录本身成为 fs.FS 的逻辑根，调用方只传 slash 分隔的相对名称。
    fileSystem := os.DirFS("./public")

    // fs.ReadFile 负责打开、读取并关闭文件；名称不应写成绝对路径。
    data, err := fs.ReadFile(fileSystem, "assets/app.css")
    if err != nil {
        fmt.Println("读取失败:", err)
        return
    }
    fmt.Println("字节数:", len(data))
}

这里的关键不是把字符串拼成 ./public/assets/app.css，而是把“目录根”和“目录内名称”分开。这样同一个读取函数可以接收 os.DirFS、embed.FS 或测试用的 fstest.MapFS。

Open 的名称必须遵守 io/fs 路径规则

fs.FS 的 Open 名称使用正斜杠分隔，并且应满足 fs.ValidPath。常见有效名称是 "."、"index.html" 和 "assets/app.css"；空字符串、以斜杠开头、包含 .. 或连续斜杠的名称都不应当作为正常的 FS 路径。

func readAsset(fileSystem fs.FS, name string) ([]byte, error) {
    // 先拒绝绝对路径和路径清理结果，避免把 OS 路径误当成 FS 名称。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("非法 FS 路径 %q", name)
    }

    // ReadFile 会在完成读取后关闭返回的文件句柄。
    return fs.ReadFile(fileSystem, name)
}

Windows 也遵守这套 slash 路径规则。反斜杠和冒号可以作为普通字符存在，但 FS 实现不能把它们当成路径分隔符。对外部输入做名称转换时，不要简单地把 filepath.Join 的结果直接交给 fs.FS。

为什么 DirFS 不是安全沙箱

os.DirFS("/srv/app") 只能说明普通打开请求以 /srv/app 为前缀开始解析。如果 /srv/app/assets/logo.svg 是指向目录外的符号链接，操作系统仍可能沿着链接访问外部目标。相对目录还会受后续 Chdir 影响，因此相对 dir 不能当成稳定的绝对根。

这一区别决定了选型：

一套可复用的判断流程

1. 先确认调用方需要的是 fs.FS，并把目录根与内部名称分成两个参数。
2. 对来自请求、配置或归档的名称调用 fs.ValidPath，不要用字符串替换代替路径规则。
3. 如果目录内容可信，使用 os.DirFS，并明确记录符号链接仍可能指向外部。
4. 如果目录内容不完全可信，或需求明确要求不能越出根目录，使用 os.Root.FS，不要把 DirFS 当安全边界。

记住一句话：DirFS 解决的是“以目录为根提供 fs.FS 接口”，不是“把进程锁进目录”。接口抽象、路径合法性和安全隔离是三个不同层次的问题。

相关问题

os.DirFS 的 dir 可以传空字符串吗？

不可以。官方文档明确要求 dir 不能是空字符串；应传入有效的目录路径。

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

不会。它只判断名称是否符合 fs.FS.Open 的路径格式，文件是否存在仍要由打开或读取操作返回错误。

什么时候不能只用 os.DirFS？

当目录中存在不应越出的符号链接，或调用代码处理不可信目录内容时，应优先评估 os.Root.FS 的强约束能力。