os.DirFS 的路径为什么不能包含上级跳转，安全边界是什么

os.DirFS 之所以不接受 ../secret，不是因为它先把路径“清理”后再打开，而是因为返回值遵守 io/fs 的统一路径语法：名称必须是未根化、以斜杠分隔的 UTF-8 路径，除根名称 . 外，任何路径段都不能是 .、.. 或空字符串。

但这只是调用参数的词法边界。os.DirFS 不是 chroot：根目录里的符号链接仍可能指向目录外；如果传给 DirFS 的根是相对路径，后续 os.Chdir 还会改变它对应的位置。需要把不可信目录树真正限制在根内时，应考虑 os.OpenRoot 返回的 Root，再使用 Root.FS()。

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

io/fs 接受的是逻辑路径，不是系统路径

fs.FS 为不同文件系统定义了一套与宿主操作系统无关的名称格式。合法名称类似 assets/app.js，根目录用单独的 . 表示。以下形式都不合法：

这套规则让内存文件系统、ZIP 文件系统、嵌入文件系统和操作系统目录使用同一种调用约定。在 Windows 上也仍以正斜杠分段；反斜杠和冒号可以作为普通字符存在，但 FS 实现不能把它们解释成路径分隔符。

为什么不能先 path.Clean 再交给 DirFS

把用户输入先做 path.Clean，再判断是否安全，容易把“拒绝非法输入”变成“悄悄改写输入”。例如 a/../secret 会被整理成 secret，调用最终可能成功，但它已经不是用户原本表达的层级。更清晰的接口体验是：业务入口先用 fs.ValidPath 拒绝非法名称，并返回可以识别的错误。

package assets

import (
    "errors"
    "io/fs"
)

var ErrInvalidAssetPath = errors.New("资源路径格式无效")

func ReadAsset(fsys fs.FS, name string) ([]byte, error) {
    // 在业务边界直接拒绝上级跳转、绝对路径和空路径段
    if !fs.ValidPath(name) || name == "." {
        return nil, ErrInvalidAssetPath
    }

    // 校验通过后仍由具体 FS 决定文件是否存在及是否可读
    return fs.ReadFile(fsys, name)
}

这里额外拒绝 .，因为这个函数只允许读取文件，不接受“读取整个根目录”的含糊请求。若接口本来就支持列目录，则应保留 .，并在 fs.ReadDir 一侧处理。

DirFS 的根不是 chroot

os.DirFS("/srv/public").Open("img/a.png") 的基本含义接近打开 /srv/public/img/a.png。它保证操作系统收到的打开路径以给定目录为前缀，却不会自动把目录变成隔离沙箱。

关键风险是符号链接。假设 /srv/public/current 是一个指向 /srv/private 的符号链接，那么调用名称 current/config.json 完全满足 fs.ValidPath，但操作系统解析链接后仍可能访问根目录之外。也就是说：

• ../secret 被拒绝，解决的是调用名称直接上跳；
• link/secret 可能合法，符号链接目标由操作系统继续解析；
• 因此 DirFS 适合可信目录树的统一读取接口，不等于通用安全沙箱。

相对根目录还会受 Chdir 影响

os.DirFS("public") 中的 public 是相对于当前工作目录解释的。创建 DirFS 返回值后，如果进程又调用 os.Chdir，同一个 FS 后续可能落到另一个 public 目录。库代码和长期运行的服务应优先使用已经确定的绝对目录。

package assets

import (
    "io/fs"
    "os"
    "path/filepath"
)

func OpenAssets(dir string) (fs.FS, error) {
    // 固定为绝对路径，避免后续 Chdir 改变 DirFS 的根位置
    absDir, err := filepath.Abs(dir)
    if err != nil {
        return nil, err
    }
    return os.DirFS(absDir), nil
}

绝对根解决的是工作目录漂移，不解决符号链接逃逸。两类问题要分别处理，不能把 filepath.Abs 当成目录隔离机制。

不可信目录树改用 os.Root.FS

当前 Go 标准库文档明确建议：需要防止通过符号链接逃出目录树时，使用 Root.FS。先用 os.OpenRoot 打开受约束根，再把它暴露为 fs.FS：

package assets

import (
    "io/fs"
    "os"
)

func ReadFromRoot(dir, name string) ([]byte, error) {
    // 先校验 io/fs 名称，给调用方稳定且明确的错误边界
    if !fs.ValidPath(name) || name == "." {
        return nil, ErrInvalidAssetPath
    }

    // OpenRoot 把后续路径操作限制在指定目录树内
    root, err := os.OpenRoot(dir)
    if err != nil {
        return nil, err
    }
    defer root.Close() // 用完释放根目录句柄

    return fs.ReadFile(root.FS(), name)
}

os.Root.FS 适合上传解包区、插件目录、租户文件区等“目录内容可能不可信”的场景。若项目需要兼容不含该 API 的旧 Go 版本，应把版本约束写入构建基线，并采用操作系统级隔离或经过专门审查的安全打开方案；不要仅依赖字符串前缀判断。

字符串前缀检查为什么不可靠

把目标路径拼接后检查 strings.HasPrefix(target, root)，既可能混淆 /srv/public 与 /srv/public-old，也看不到符号链接解析后的真实位置。即便再配合 filepath.Clean，仍然只是在处理字符串，不等于约束操作系统的路径解析。

常见问题

DirFS.Open 会接受反斜杠吗？

io/fs 在所有平台都使用正斜杠分段。反斜杠可以作为名称中的普通字符通过 ValidPath，但 FS 实现不应把它当成分隔符。接收 Windows 风格用户输入时，应先明确产品输入格式，不能直接把反斜杠当作跨平台目录语义。

fs.ValidPath 通过就一定安全吗？

不一定。它只说明名称符合 io/fs 语法，不证明文件存在、权限允许、符号链接目标仍在根内，也不代表当前用户有权读取该文件。

embed.FS 也遵守相同路径规则吗？

是。它实现 fs.FS，调用名称遵守同一套未根化、斜杠分隔的路径语法。不同之处在于文件来自编译时嵌入内容，不存在运行时目录树被替换为外部符号链接的同类问题。

什么时候 os.DirFS 已经够用？

当根目录和其中的符号链接都由应用部署流程可信控制，主要目标是把普通目录适配为 fs.FS 时，DirFS 简单直接。只要目录内容可由低信任用户、压缩包或插件修改，就应提升到受约束根目录或更强的操作系统隔离。