Go fs.Sub 怎样限制嵌入文件系统的访问范围

如果一个嵌入文件系统同时包含公开模板、内部配置和构建辅助文件，最稳妥的做法通常不是把根 fs.FS 直接交给调用方，而是先用 fs.Sub 把某个子目录变成新的文件系统根。这样，调用方读取 config/app.yaml 时不需要知道上层的 public 前缀。

官方参考：https://pkg.go.dev/io/fs

核心结论：fs.Sub(fsys, "public") 会返回一个以 public 为新根的 fs.FS。它解决的是命名空间隔离和调用接口简化；路径仍然必须符合 fs.ValidPath，而且它不是针对符号链接的 chroot 安全沙箱。

先明确 Sub 解决的边界

fs.FS 的路径是统一的 slash-separated 相对路径，根目录用 . 表示。假设嵌入资源如下：

assets/
├── public/
│   └── config/app.yaml
└── internal/secret.txt

直接把根 FS 传给调用方时，调用方必须知道 public/config/app.yaml；而下面的写法把 public 变成了新的根：

package main

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

//go:embed assets
var embedded embed.FS

func main() {
	// 这里的目录名必须是符合 fs.ValidPath 的相对路径。
	publicFS, err := fs.Sub(embedded, "assets/public")
	if err != nil {
		// Sub 失败通常表示 dir 不是合法的 FS 路径。
		panic(err)
	}

	// 子 FS 的根目录已经是 assets/public，不再重复传入前缀。
	data, err := fs.ReadFile(publicFS, "config/app.yaml")
	if err != nil {
		// 真实项目中可按 errors.Is 区分 ErrNotExist 等具体原因。
		panic(err)
	}
	fmt.Println(string(data))
}

实现上，如果底层 FS 实现了 fs.SubFS，fs.Sub 会优先调用它的 Sub 方法；否则标准库会返回一个代理 FS，把子 FS 上的相对路径转换回底层 FS 的完整路径。对调用方而言，两种情况都保持同一个 fs.FS 接口。

比较根 FS、Sub FS 和额外校验

这三个方案不是互相替代的“安全等级”，而是解决不同的接口问题：

例如模板渲染器只需要 public/templates，应把这个目录转换为它自己的 FS；而资源管理器需要列出 public 和 internal 两个顶层目录时，直接使用根 FS 更自然。若业务只允许读取一个固定配置文件，Sub FS 之外再加白名单会更清楚，但那是业务规则，不是 fs.Sub 自动提供的能力。

用 ValidPath 处理相对路径

fs.ValidPath 判断的是能否作为 FS.Open 的路径名。.、config/app.yaml 和 assets/logo.svg 合法；空字符串、..、以斜杠开头的绝对路径、重复斜杠以及包含 ./ 或 ../ 元素的路径不合法。Windows 上也按斜杠分隔，反斜杠不能被 FS 实现当成路径分隔符。

package main

import (
	"fmt"
	"io/fs"
)

func acceptResource(name string) error {
	// 先拒绝不符合 io/fs 约定的路径，避免把清洗责任推给底层实现。
	if !fs.ValidPath(name) {
		return fmt.Errorf("invalid resource path %q", name)
	}
	// 通过 ValidPath 只说明路径形状合法，文件是否存在仍要交给 FS 判断。
	fmt.Printf("path accepted: %s\\n", name)
	return nil
}

需要注意，ValidPath 不是文件存在性检查，也不是业务白名单。config/missing.yaml 可能形状合法但不存在；config/app.yaml 形状合法，也不代表当前 FS 一定允许读取它。

读取文件并处理失败

获得 Sub FS 后，统一使用相对路径调用 fs.ReadFile 即可。建议把路径校验、读取和错误分类放在一个小函数里，让上层不再拼接 public 前缀：

package assets

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

// ReadConfig 只从传入的子文件系统读取配置文件。
func ReadConfig(fsys fs.FS, name string) ([]byte, error) {
	// 先做形状检查，避免把非法路径交给具体 FS 实现。
	if !fs.ValidPath(name) {
		return nil, fmt.Errorf("invalid asset path %q", name)
	}

	data, err := fs.ReadFile(fsys, name)
	if err != nil {
		// 让调用方能区分“路径非法”之外的文件不存在情况。
		if errors.Is(err, fs.ErrNotExist) {
			return nil, fmt.Errorf("asset %q does not exist: %w", name, err)
		}
		return nil, fmt.Errorf("read asset %q: %w", name, err)
	}
	return data, nil
}

如果 fs.Sub 的 dir 本身不是合法路径，会返回一个带 Op="sub" 的 *fs.PathError；如果目录形状合法但不存在，Sub 不会提前检查，错误通常会在后续 ReadFile、ReadDir 或 Open 时出现。这种延迟行为适合先组装资源视图、再按需访问。

确认 Sub 不是安全沙箱

对 embed.FS 或 fstest.MapFS 这类内存/只读资源，fs.Sub 很适合做模块边界。但如果底层是 os.DirFS，不要把“隐藏前缀”理解成“阻止一切宿主目录访问”。Go 官方文档特别说明：os.DirFS 不会检查目录内部指向其他目录的符号链接，因此 fs.Sub 也不会改变这一点。

所以可以按下面的规则选择：

• 嵌入资源、测试资源或明确的虚拟 FS：优先 fs.Sub，简化模块接口。
• 需要固定资源名：在 Sub FS 之上增加白名单，并继续使用 fs.ValidPath 做形状检查。
• 需要约束宿主文件系统目录树：不要只依赖 os.DirFS 和 fs.Sub，改用 Go 当前版本提供的目录树约束能力，并单独评估符号链接策略。

一张表记住怎么选

最后把职责分开就不容易出错：fs.Sub 负责重设 FS 视图的根，fs.ValidPath 负责路径形状，业务白名单负责允许哪些资源，具体 FS 则负责判断目标是否存在以及能否读取。

相关问题

fs.Sub 的目录不存在时会立即报错吗？

不会。只要 dir 的路径形状合法，fs.Sub 可以先返回子 FS；目录是否存在通常在后续访问时体现为错误。

ValidPath 能阻止符号链接跳出目录吗？

不能。它只检查路径名是否符合 io/fs 约定，不解析底层文件系统的符号链接。

子 FS 中还要写 public 前缀吗？

不需要。调用 fs.Sub(root, "public") 后，config/app.yaml 就对应原来的 public/config/app.yaml。