Go DirFS 为什么相对路径检查仍然失败

如果把 os.DirFS 当成“目录沙箱”，就会遇到一个很容易误判的现象：../secret.txt 这类路径确实打不开，但根目录里的符号链接仍可能把访问带到目录外。原因是 DirFS 解决的是“从哪个目录开始拼接”，不是所有情况下的目录树隔离。

排查这类问题，要把两个概念拆开：fs.ValidPath 检查的是 fs 路径的写法；符号链接、相对根目录变化和不可信文件名，则属于访问边界问题。

先分清 fs 路径和操作系统路径

io/fs 规定的路径是 UTF-8、使用斜杠分隔的未根路径。. 表示根目录，docs/readme.md 是合法的相对 fs 路径；开头的 /、路径元素 ..、连续斜杠和结尾斜杠都不符合 fs.ValidPath。

因此，下面的检查只能回答“这个名字能否作为 fs.FS 的 Open 参数”，不能回答“最终访问是否永远留在某个物理目录内”。

package main

import (
	"fmt"
	"io/fs"
)

func main() {
	paths := []string{".", "docs/readme.md", "../secret.txt", "/etc/passwd", `docs\\readme.md`}
	for _, name := range paths {
		// ValidPath 只判断 fs 路径语法，不解析磁盘上的符号链接。
		fmt.Printf("%q: %v\n", name, fs.ValidPath(name))
	}
}

这里的反斜杠不会被 io/fs 当成路径分隔符；Windows 路径也必须按 fs 规则使用斜杠。另一个常见错误是先用 filepath.Join 拼出操作系统路径，再把结果直接交给 fs.FS.Open，这样会混淆两套路径语义。

为什么检查通过仍可能越过目录树

os.DirFS(root) 返回一个以 root 为起点的 fs.FS。在普通文件上，fsys.Open("docs/readme.md") 可以理解成从这个根目录继续打开文件。但如果 docs/link 是指向外部目录的符号链接，link/passwd 的字符串本身完全可以通过 fs.ValidPath，随后由操作系统继续解析链接。

这也是“相对路径检查失败”的本质：相对只描述名字形式，不代表物理位置一定被锁定。另外，os.DirFS("relative") 使用相对根目录时，后续调用 Chdir 还可能改变它对应的实际位置。固定根目录和不可信文件名时，不要把这两件事当成同一层防护。

按威胁边界选择修正方式

如果文件名来自可信配置，DirFS 适合表达“从某个目录读取”。如果只是要拒绝词法上的越界，可以在进入业务逻辑前使用 filepath.IsLocal，但这仍不等于抵抗符号链接竞态。

从 Go 1.24 开始，更明确的做法是使用 os.OpenRoot，再通过 Root.FS 暴露为 fs.FS。Root 的方法会拒绝通过 .. 或指向根外的符号链接逃逸，适合归档解压、上传文件落盘等不可信文件名场景。

package main

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

func readUnderRoot(dir, name string) error {
	root, err := os.OpenRoot(dir)
	if err != nil {
		return fmt.Errorf("打开根目录失败: %w", err)
	}
	defer root.Close() // Root 持有目录句柄，使用完必须释放。

	secureFS := root.FS()
	if !fs.ValidPath(name) {
		return fmt.Errorf("非法 fs 路径: %q", name)
	}
	data, err := fs.ReadFile(secureFS, name)
	if err != nil {
		return fmt.Errorf("读取根目录内文件失败: %w", err)
	}
	fmt.Printf("读取 %d 字节\n", len(data))
	return nil
}

如果项目需要兼容没有 os.Root 的旧 Go 版本，至少要明确写出“只做词法检查”的安全边界，并考虑升级或采用经过维护的安全打开方案。不要把先 EvalSymlinks、再 Open 当成无竞态的最终方案。

一张表记住判断顺序

最后记住：fs.ValidPath 是输入格式检查，DirFS 是文件系统适配，os.Root 才是针对目录树逃逸语义设计的约束工具。把三者职责分清，才能知道“检查失败”究竟是路径写法错了，还是选择的隔离机制不够。

相关问题

DirFS 能替代 chroot 吗？

不能。官方文档明确提醒，DirFS 不是 chroot 风格的安全机制，尤其不能阻止目录内符号链接把访问带向外部。

fs.ValidPath 会检查符号链接吗？

不会。它只判断传入名称是否符合 fs 路径规则，不访问磁盘，也不解析链接。

什么时候仍然适合使用 DirFS？

当根目录和文件名都由可信代码控制，且需求只是把一个目录适配为 fs.FS 时，DirFS 仍然简单直接；遇到不可信文件名时，应重新评估边界。