Go os.DirFS 如何安全暴露子目录：路径清理、Open 语义与测试边界

把静态文件目录交给 Go 服务时，最容易留下的坑不是端口，而是“根目录到底是谁”。如果代码一边用绝对路径拼接文件名，一边又想获得 io/fs 的统一接口，路径清理、跨平台分隔符和目录越界就会混在一起。更稳妥的做法是先用 os.DirFS 固定一个根，再让调用方只提交 slash 分隔的相对路径，最后用测试把允许和拒绝的边界锁住。

先把三种目录写法放到同一个问题里

假设服务只允许读取项目里的 public 目录。直接写 os.ReadFile(filepath.Join(root, name)) 看起来简单，却把“用户输入是什么格式”和“根目录在哪里”交给了每个调用点。换成 os.DirFS(root) 后，文件系统的根被固定下来，调用者只需要提交 assets/app.css 这样的 FS 名称。

os.DirFS 的根目录语义：Open 看到的不是绝对路径

os.DirFS("./public") 建立了一个以 public 为根的 FS。对它调用 Open("assets/app.css")，实际访问的是 ./public/assets/app.css；调用 Open("/etc/hosts") 则不应该被当成宿主机路径。这个区别很重要：业务函数的参数名最好直接叫 name 或 fsName，不要继续叫 path，否则后续很容易把两套语义混写。

package main

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

func readAsset(root, name string) ([]byte, error) {
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid fs name %q", name)
    }
    public := os.DirFS(root)
    return fs.ReadFile(public, name)
}

这里的校验顺序是先检查 FS 名称，再读取文件。fs.ValidPath 要求路径使用斜杠，并拒绝空串、绝对路径、. 之外的 .. 元素和重复分隔符。它解决的是“输入是否符合 FS 名称约定”，不是“调用进程有没有权限读取这个文件”。

fs.Sub 什么时候比重复拼接目录更清楚

如果下游模块只应该看到 public/assets，可以把这个子目录交给它：

root := os.DirFS("./public")
assets, err := fs.Sub(root, "assets")
if err != nil {
    return err
}

data, err := fs.ReadFile(assets, "app.css")
if err != nil {
    return err
}
_ = data

这样下游只知道 app.css，不需要知道上层的 public/assets。目录边界也集中在创建 assets 的地方。若模块同时接收用户输入，仍然要保留 fs.ValidPath 检查，并根据内容类型、大小和符号链接策略补充更高层约束。

用一组边界测试确认“安全”说到哪一步

不要只测试一个正常文件。临时目录里写入 assets/app.css 后，下面这组表格就是最小验收口径：

func TestReadAssetNames(t *testing.T) {
    root := t.TempDir()
    if err := os.MkdirAll(filepath.Join(root, "assets"), 0o755); err != nil {
        t.Fatal(err)
    }
    if err := os.WriteFile(filepath.Join(root, "assets", "app.css"), []byte("ok"), 0o644); err != nil {
        t.Fatal(err)
    }

    tests := []struct {
        name string
        want bool
    }{
        {".", true},
        {"assets/app.css", true},
        {"../secret.txt", false},
        {"/etc/hosts", false},
        {"assets/missing.css", false},
    }
    _ = tests
}

示例省略了断言展开，但每一项都应分别记录 ValidPath 结果和 fs.ReadFile 的错误。注意 . 是一个合法的 FS 名称，打开它得到目录；“合法”不等于“它就是业务允许的文件”。

不要把 ValidPath 当成完整的访问控制

ValidPath 不会替你判断符号链接最终指向哪里，也不会替你设置 Unix 权限、Windows ACL、文件大小上限或响应头。对公开静态文件服务，目录权限、内容类型、缓存策略和错误响应仍然要单独检查。若需求是“严格限制在某个目录及其子树内”，应进一步阅读当前 Go 版本的 os.DirFS 文档和实现说明，并用目标平台上的符号链接用例做验证。

常见问题

os.DirFS 会自动把路径变成安全路径吗？

它提供 FS 根目录语义，但不等于完成全部安全审计。输入格式、权限、符号链接和资源大小仍需要业务侧判断。

为什么 Open("/etc/hosts") 不应该当作绝对路径读取？

FS API 的参数是 slash 分隔的名称，根由 FS 实现决定；把宿主机绝对路径直接传进去会混淆两套路径语义。

fs.Sub 能替代所有前缀拼接吗？

它适合把固定子目录封装给下游，但动态用户输入仍要做名称校验和权限策略，不能只靠移动根目录。

小结

选择 os.DirFS 的核心收益，是把“根目录”从每次读取的字符串拼接中拿出来。配合 fs.Sub 可以继续收窄模块边界，配合 fs.ValidPath 可以先过滤明显不合法的 FS 名称。最终是否安全，要以目标平台、权限和符号链接测试的实际结果为准。