Go os.DirFS 配合 fs.ValidPath 怎么限制相对路径

把用户输入交给 os.Open，很容易把“文件名”误当成“固定目录下的资源名”。如果应用只允许读取 public 目录，比较稳妥的做法是：先按 io/fs 的规则接收一个不带盘符和前导斜杠的相对路径，再用 fs.ValidPath 拒绝空路径、. 以外的点号元素、..、重复斜杠和首尾斜杠，最后交给 os.DirFS。需要防止目录内符号链接跳出根目录时，单靠这两个 API 还不够，要改用 os.OpenRoot。

结论：fs.ValidPath 负责“这个名字是否符合 io/fs 语法”，os.DirFS 负责把路径解释在某个目录树下；它们都不会自动把目录内的符号链接变成不可逃逸的安全边界。

先把用户输入定义成 io/fs 路径

io/fs 的路径不是操作系统原生路径，而是跨平台的逻辑名字：元素之间永远用 / 分隔，不能以 / 开头或结尾，不能出现空元素、. 或 ..，根目录只有特殊名字 .。因此，docs/readme.txt 可以作为资源名，/etc/passwd、docs/../secret 和 docs//readme.txt 都应在进入文件系统前被拒绝。

如果接口约定的是 URL 风格资源名，还应在业务层明确拒绝反斜杠。因为 fs.ValidPath 把反斜杠当普通字符，而不是路径分隔符；这是它的跨平台契约，不代表你的 URL 路由也应该接受这种写法。

func validateResourcePath(name string) error {
	// 业务接口采用 URL 风格路径，避免把反斜杠当成另一套输入语法。
	if strings.ContainsRune(name, '\\') {
		return fmt.Errorf("反斜杠不是资源路径分隔符")
	}
	// 不要先 filepath.Clean，否则可能把非法的 .. 输入改写成合法路径。
	if !fs.ValidPath(name) {
		return fmt.Errorf("非法 io/fs 路径: %q", name)
	}
	if name == "." {
		return fmt.Errorf("接口只允许读取文件，不允许打开根目录")
	}
	return nil
}

用 os.DirFS 读取相对路径

os.DirFS("public") 返回一个 fs.FS，后续调用使用的是相对资源名，不再由业务代码手工拼接绝对路径。校验函数和打开动作应放在同一个小函数里，确保新增调用方不会忘记检查输入。

func readAsset(fsys fs.FS, name string) ([]byte, error) {
	if err := validateResourcePath(name); err != nil {
		return nil, err
	}
	// fs.ReadFile 会调用 fsys.Open，并在读取结束后关闭文件。
	data, err := fs.ReadFile(fsys, name)
	if err != nil {
		return nil, fmt.Errorf("读取资源 %q: %w", name, err)
	}
	return data, nil
}

func loadReadme() ([]byte, error) {
	// public 是资源根目录；调用方只传 docs/readme.txt 这类逻辑路径。
	fsys := os.DirFS("public")
	return readAsset(fsys, "docs/readme.txt")
}

这里的关键不是 DirFS 会自动“消毒”路径，而是它把文件访问接口改成了 fs.FS。fs.FS.Open 的实现应拒绝不满足 ValidPath 的名字；在应用层提前检查，则可以把错误变成统一的输入错误，并避免不同文件系统实现出现不一致。

fs.ValidPath 能挡住什么，不能挡住什么

第一类误区是把 filepath.Clean 当成安全校验。清理路径的目标是得到规范化结果，不是保留攻击输入；一旦先清理，a/../b 可能变成 b，应用就失去了记录和拒绝原始越界意图的机会。对外部资源名，应该先按契约检查，再决定是否允许。

第二类误区是以为 DirFS 会阻止所有逃逸。官方文档明确说明，DirFS 仍会跟随目录树中的符号链接；如果 public/out 指向根目录外的位置，读取 out/config 仍可能访问到外部内容。这个问题和 .. 是否存在是两条不同的安全链路。

另外，DirFS("relative") 使用相对根目录时还会受到后续 os.Chdir 的影响。长生命周期服务应优先传入稳定的绝对目录，或直接使用根句柄。可以用下面的清单做代码评审：

• 是否在任何 Open、ReadFile、WalkDir 前检查了逻辑路径？
• 是否把 .. 清理掉后当成校验通过？
• 资源目录是否允许上传者创建符号链接？如果允许，是否需要根句柄隔离？

需要根目录安全边界时改用 os.Root

Go 1.24 增加了 os.OpenRoot。它打开一个目录根，Root.FS 返回的文件系统会限制符号链接不能引用根目录外的位置。仍然建议保留 fs.ValidPath，因为“名字合法”和“访问不会逃逸”分别属于输入协议与物理访问边界。

func readFromConfinedRoot(rootDir, name string) ([]byte, error) {
	if err := validateResourcePath(name); err != nil {
		return nil, err
	}
	root, err := os.OpenRoot(rootDir)
	if err != nil {
		return nil, fmt.Errorf("打开资源根: %w", err)
	}
	defer root.Close() // Root 持有目录句柄，使用完必须释放。

	return readAsset(root.FS(), name)
}

如果项目仍需兼容没有 os.OpenRoot 的 Go 版本，可以继续使用 DirFS，但要把资源目录当成“信任边界之外的普通目录”管理：禁止不受控的符号链接、固定绝对根路径，并在部署和上传流程中检查目录内容。不要把兼容方案描述成等价的根隔离。

常见问题

fs.ValidPath("a\\b") 为什么可能返回 true？

因为 io/fs 规定所有系统都用斜杠分隔，反斜杠只是文件名中的普通字符。若你的接口是 URL 路径，应在业务层额外拒绝它。

验证通过后还能读取不到文件吗？

可以。ValidPath 只说明名字合法，文件仍可能不存在、权限不足、是目录，或被运行时删除。读取结果仍要处理 error。

只禁止 .. 就够了吗？

不够。还要拒绝绝对路径、重复斜杠和不符合接口约定的分隔符；如果目录内存在外部符号链接，还要用 os.Root 或收紧目录写入权限。

进一步核对 API 语义时，可直接查看 io/fs.ValidPath、os.DirFS 和 os.OpenRoot 的官方文档。把输入规范、逻辑文件系统和物理根隔离分别建模，路径安全代码会更容易复用和审查。