把多个目录、嵌入资源和测试文件系统拼成一个统一入口时，fs.Sub 很顺手，但它最容易被误解的地方也在这里：它创建的是“从某个子目录开始看的文件系统视图”，不是操作系统级的沙箱。嵌套调用时，第二层 dir 相对于第一层子 FS 的根目录解析；如果底层是 os.DirFS，内部符号链接仍可能把访问带到子目录之外。

记住一句话：fs.Sub 负责组合命名空间，os.Root 或 os.OpenInRoot 才负责约束不可信本地路径的访问范围。

先把要保护的资产和根目录说清楚

我在静态资源装配里通常会遇到三层名字：原始文件系统里有 assets/，它下面有 templates/，业务代码只想看到模板目录中的文件。此时最重要的不是把完整物理路径传来传去，而是明确每一层的逻辑根目录：

• 原始 FS：拥有 assets/templates/email/welcome.html 的文件系统。
• 第一层子 FS：把 assets 映射为当前根目录。
• 第二层子 FS：再把第一层里的 templates 映射为当前根目录。
• 业务读取：只需要打开 email/welcome.html，不再知道前面的目录前缀。

这样的拆分能让模块只依赖 fs.FS，也方便把 embed.FS、fstest.MapFS 或真实目录接到同一个接口上。这里的“根目录”是 API 看到的路径起点，不等于底层操作系统已经替你做了权限隔离。

用嵌套 fs.Sub 组合业务目录

fs.Sub 的核心语义可以简化为：先验证传入的 dir 是合法的 FS 路径，再返回一个新的视图；对普通实现来说，子视图的 Open(name) 效果接近于把 dir 和 name 用 path.Join 拼起来后交给原 FS。下面的例子用内存文件系统表达目录关系，代码本身只展示组合方式。

package main

import (
    "fmt"
    "io/fs"
    "log"
    "testing/fstest"
)

func buildTemplateFS() (fs.FS, error) {
    source := fstest.MapFS{
        "assets/templates/email/welcome.html": &fstest.MapFile{
            Data: []byte("
Welcome
"),
        },
        "assets/images/logo.svg": &fstest.MapFile{
            Data: []byte(""),
        },
    }

    // 第一层把 assets 设为根，第二层只暴露 templates 目录。
    assets, err := fs.Sub(source, "assets")
    if err != nil {
        return nil, fmt.Errorf("切出 assets: %w", err)
    }
    templates, err := fs.Sub(assets, "templates")
    if err != nil {
        return nil, fmt.Errorf("切出 templates: %w", err)
    }
    return templates, nil
}

func main() {
    templates, err := buildTemplateFS()
    if err != nil {
        log.Fatal(err)
    }

    // 这里的路径相对 templates 的根目录，而不是相对原始 source。
    data, err := fs.ReadFile(templates, "email/welcome.html")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(data))
}

第二次调用传入的是 templates 这个子 FS，所以 fs.Sub(assets, "templates") 正确；如果误写成 fs.Sub(assets, "assets/templates")，就把原始目录前缀重复了一遍。另一个细节是，fs.Sub 不会因为目录暂时不存在就立刻报错，它通常在后续打开文件时才暴露缺失资源。

攻击路径从“路径写错”升级到“链接越界”

从排错角度看，根目录问题可以分成几层。第一层只是业务路径写错：子 FS 内应该使用 email/welcome.html，却传入了原始 FS 的长路径。第二层是 dir 本身不满足 fs.ValidPath，例如包含空元素、绝对路径或 .. 元素。第三层才是安全边界：底层文件系统允许符号链接，而链接目标位于当前逻辑目录之外。

官方文档明确说明，fs.Sub 不会改变 os.DirFS 的符号链接行为。比如 os.DirFS("/srv/app") 再切出 public，只是让调用者以 public 为逻辑起点；如果 public/cache-link 指向外部目录，读取该链接仍可能触达外部内容。因此，图里的“子视图边界”和“安全访问边界”必须分开记录。

按风险分级处理根目录边界

这个分级很有用，因为“目录不存在”和“目录越界”不应该被同一种重试逻辑掩盖。前者可能是部署顺序问题，后者是访问模型不匹配；如果代码只看到一个统一的“读取失败”，后续的补偿动作反而可能扩大风险。

不可信本地路径要换成 os.Root

如果业务目标是“只允许在某个真实目录树内打开文件”，就应该使用 Go 1.24 引入的 os.Root 系列 API。官方说明中，Root 的方法会拒绝通过 .. 或指向根目录外的符号链接逃逸；一次性读取可以使用 os.OpenInRoot，需要多次操作时可以持有一个根对象并在结束时关闭。

package main

import (
    "fmt"
    "io"
    "os"
)

func readUserFile(baseDir, name string) ([]byte, error) {
    // name 可能来自请求或归档内容，不把它与 baseDir 手工拼接。
    file, err := os.OpenInRoot(baseDir, name)
    if err != nil {
        return nil, fmt.Errorf("打开受限文件: %w", err)
    }
    defer file.Close() // 读取完成后释放文件描述符。
    return io.ReadAll(file)
}

func readManyFiles(baseDir string, names []string) error {
    root, err := os.OpenRoot(baseDir)
    if err != nil {
        return fmt.Errorf("打开受限根目录: %w", err)
    }
    defer root.Close() // 根对象持有系统资源，批量读取结束后释放。

    for _, name := range names {
        file, err := root.Open(name)
        if err != nil {
            return fmt.Errorf("打开 %q: %w", name, err)
        }
        if err := file.Close(); err != nil {
            return fmt.Errorf("关闭 %q: %w", name, err)
        }
    }
    return nil
}

上面的第一段为了突出 API 选择，实际业务中应把打开后的文件读完并关闭；如果要返回内容，可以把 os.OpenInRoot 得到的文件交给读取逻辑，再显式关闭。关键区别不在于“有没有先调用 filepath.Clean”，而在于打开动作本身使用了带根目录约束的 API。

fs.Sub 仍然可以和安全根目录配合：先由 os.Root 负责约束真实目录，再把一个实现了 fs.FS 的安全入口按业务模块切出子视图。这样分工更清晰：Root 负责防越界，Sub 负责让模板、附件或缓存模块只看到自己的逻辑目录。

审计记录要同时保存物理根和逻辑名

在多层组合场景里，日志只记录“读取成功”不够复查。建议至少记录三项：组合链的逻辑根，例如 assets/templates；调用者提交的相对名，例如 email/welcome.html；最终结果是成功、路径不存在还是被安全根拒绝。不要把用户输入直接拼进日志格式字符串，也不要为了方便把完整物理路径暴露给不需要它的调用方。

package main

import (
    "log/slog"
    "path"
)

func recordRead(logger *slog.Logger, logicalRoot, name string, err error) {
    // 用 path.Join 展示逻辑位置；它不承担真实文件系统的安全校验。
    logicalPath := path.Join(logicalRoot, name)
    if err != nil {
        logger.Warn("文件系统读取失败", "logical_path", logicalPath, "error", err)
        return
    }
    logger.Info("文件系统读取成功", "logical_path", logicalPath)
}

这里的 path.Join 只用于审计字段，不能替代 os.Root 的访问控制。审计值与访问值分开处理，能避免后续维护者把“日志里的规范化路径”误当成已经安全打开的路径。

发布前用测试和清单复查组合关系

对于自定义 FS，实现或装配完成后可以使用 testing/fstest.TestFS 检查基本接口契约；对 fs.Sub 的组合则应专门覆盖根目录、嵌套目录、缺失目录和非法名字。这里的验证是开发阶段的测试思路，不能把它理解成 fs.Sub 自动提供了安全证明。

• 确认每次 fs.Sub 的 dir 都相对于当前 FS，而不是相对于最初的物理路径。
• 确认模块内部的 Open、ReadFile 和 WalkDir 使用的是当前逻辑根下的相对名。
• 确认 dir="." 的特殊语义没有被包装层意外改写。
• 确认代码没有把 fs.Sub(os.DirFS(...), ...) 宣称为 chroot 或完整沙箱。
• 如果路径来自外部输入，确认真正的打开动作使用 os.Root 或 os.OpenInRoot。
• 确认文件、根对象和目录句柄在错误路径上也会关闭，并让原始错误保留在包装链中。

常见问题

fs.Sub 的第二个参数可以写绝对路径吗？

不可以。io/fs 使用无前导斜杠、以斜杠分隔的相对路径，根目录用 . 表示；绝对路径、空元素和 .. 元素都不应作为合法 FS 路径。

嵌套 fs.Sub 会不会把路径前缀重复拼接？

只要第二次的 dir 相对于第一次返回的子 FS，就不会重复。错误通常来自把原始 FS 的完整前缀再次传给已经切过的视图。

fs.Sub 能防止符号链接越界吗？

不能。它改变的是命名空间起点，不会改变底层 FS 的符号链接策略。需要阻止访问根目录外的文件时，使用 os.Root 或 os.OpenInRoot。

什么时候只用 fs.Sub 就足够？

当 FS 来自可信的嵌入资源、内存测试数据或已明确受控的只读实现，并且你的目标只是隐藏目录前缀、隔离模块视图时，fs.Sub 很合适。只要输入或底层目录可能被攻击者影响，就要单独设计安全根目录。

官方资料：https://pkg.go.dev/io/fs、https://go.dev/src/io/fs/sub.go、https://go.dev/blog/osroot、https://pkg.go.dev/os。