Go DirFS 为什么路径边界没有生效

Go 的 os.DirFS 很适合把一个目录接到 io/fs 接口上，但它不是 chroot，也不会自动阻止符号链接越过根目录。最容易忽略的场景是：public/outside 是一个指向根目录外的链接，调用 fs.ReadFile(os.DirFS("public"), "outside/secret.txt") 仍可能读到链接目标。

官方地址：https://pkg.go.dev/os

如果目录内容可信，DirFS 足够方便；如果文件名或目录内容不可信，尤其是归档解压、上传文件和静态文件服务，应改用 Go 1.24 起的 os.OpenInRoot 或 os.OpenRoot(...).FS()。前者解决一次打开，后者适合继续使用 fs.FS。

DirFS 的“根”为什么没有挡住符号链接

DirFS("public") 的核心语义是把 Open(name) 变成类似 os.Open("public/" + name) 的访问。它保证系统调用从 public 开始，却不把后续的符号链接解析变成一个新的安全边界。

因此，问题不在于 fs.FS 把路径算错了，而在于“路径字符串位于目录下”和“最终跟随链接后的对象仍位于目录下”是两件事。只要根目录中存在指向外部的链接，DirFS 就不能提供后一个保证。

fs.ValidPath 只能管路径格式

io/fs 要求传给 FS.Open 的名字是斜杠分隔的相对路径。可以先用 fs.ValidPath 拒绝绝对路径、空路径片段和显式的 ..，但它只检查字符串，不会读取文件系统，也不知道某个组件是不是符号链接。

package main

import (
	"fmt"
	"io/fs"
)

func acceptFSName(name string) error {
	// 先拦截不符合 io/fs 约定的路径格式。
	if !fs.ValidPath(name) {
		return fmt.Errorf("非法的 fs 路径: %q", name)
	}
	// 合法只代表路径格式正确，不代表解析后的对象仍在根目录内。
	return nil
}

所以，把 fs.ValidPath 和 os.DirFS 叠加，并不能修复符号链接逃逸。它们分别解决“输入是否是合法 FS 路径”和“如何从目录开始打开”两个问题。

单次读取不可信文件名用 OpenInRoot

如果调用方只需要打开一个上传文件、归档成员或用户提供的相对路径，Go 1.24 及以上可以直接使用 os.OpenInRoot。它会拒绝使任意组件落到目录外的路径，也会拒绝指向根目录外的符号链接。

package main

import (
	"io/fs"
	"os"
)

func readWithDirFS(rootDir, name string) ([]byte, error) {
	// 这段写法适合可信目录，但不会阻止根目录内的符号链接指向外部。
	return fs.ReadFile(os.DirFS(rootDir), name)
}

如果 name 或目录内容可能被外部影响，应直接使用带边界的文件句柄，而不是打开后再根据 f.Name() 重新读取：

func readUnderRoot(rootDir, name string) ([]byte, error) {
	// name 可以来自请求或归档条目，不能先 filepath.Join 后自行判断。
	f, err := os.OpenInRoot(rootDir, name)
	if err != nil {
		return nil, fmt.Errorf("打开根目录内文件: %w", err)
	}
	defer f.Close() // 保证句柄在所有返回路径上关闭。

	data, err := io.ReadAll(f)
	if err != nil {
		return nil, fmt.Errorf("读取文件: %w", err)
	}
	return data, nil
}

第二段需要额外导入 io。关键点是：打开动作本身已经带着根目录约束，后续不要把原始 name 再交给普通的 os.Open。

需要 fs.FS 时用 Root.FS

如果下游 API 接收的是 fs.FS，可以先打开一个根对象，再把它转换成受保护的文件系统：

package main

import (
	"io/fs"
	"os"
)

func makeSafeFS(rootDir string) (fs.FS, func() error, error) {
	// Root 持有根目录句柄，避免把 DirFS 误当成符号链接沙箱。
	root, err := os.OpenRoot(rootDir)
	if err != nil {
		return nil, nil, err
	}
	// 调用方使用完 FS 后必须调用 close，释放 Root 的资源。
	return root.FS(), root.Close, nil
}

Root.FS() 适合交给模板渲染、静态资源或归档读取等只认识 fs.FS 的组件。它允许仍在根目录内的相对路径和符号链接，但不会允许链接目标落到根目录外。

按边界选择方案

还要留意版本与平台：os.Root 从 Go 1.24 引入；官方文档也说明它不阻止 Linux bind mount、文件系统边界或 Unix 设备文件访问，GOOS=js 的符号链接校验还存在平台限制。升级版本并不意味着可以跳过权限、挂载和进程隔离设计。

常见追问

把路径先 filepath.Clean 一次就够了吗？

不够。Clean 只能整理字符串中的点段，无法阻止符号链接在真正打开时改变路径含义，也不能替代带根目录约束的打开 API。

DirFS 是否完全不能用？

不是。对应用自己生成、不会被外部写入且不含任意符号链接的目录，DirFS 仍然是清晰的 fs.FS 适配器。只有“目录或文件名可能被攻击者影响”时，才需要把边界升级到 os.Root 或更强的操作系统隔离。