Go fs.ValidPath 怎样检查虚拟文件名

我在把上传文件、模板名或嵌入资源交给 io/fs.FS 时，最容易先想到的是“把它拼成路径再打开”。但虚拟文件系统的名称并不跟着当前操作系统切换规则：它始终是 UTF-8、未根路径、用斜杠分隔的路径名。要在进入 FS.Open 前挡住空段和路径穿越，直接调用 fs.ValidPath；它检查的是名称语法，不检查文件是否存在。

官方文档：https://pkg.go.dev/io/fs

fs.ValidPath(name) 返回 true 的条件是：名称是合法的虚拟路径；单独的 . 表示根目录，其他 .、..、空路径段、首尾斜杠和重复斜杠都会被拒绝。通过校验后，还要让具体的 FS.Open 实现负责访问和错误处理。

先分清“路径合法”与“文件存在”

ValidPath 不会读取磁盘，也不会调用 Open、Stat 或网络存储。它只对传入的字符串做语法判断，所以一个不存在的 docs/readme.md 仍可能返回 true，而是否存在要留给后续的文件系统操作。

这正适合资源服务的入口：先在统一的虚拟命名空间里做一次轻量校验，再把通过的名称交给 FS.Open。这样，输入校验、存储查找和错误响应各自有清晰边界，代码也不会把宿主机的路径规则误带进来。

这些名称会通过，哪些会被拒绝

下面的判断可以先记成一句话：名称按斜杠拆分后，每个元素都不能是空字符串、. 或 ..；唯一的例外是整个名称恰好为 .，它代表根目录。

最小示例可以把结果直接打印出来。代码只展示 API 的语义，不把输出当作本机运行截图或安全证明。

package main

import (
	"fmt"
	"io/fs"
)

func main() {
	paths := []string{".", "assets/logo.svg", "", "../secret", "assets//logo.svg", "/assets/logo.svg", "assets/logo.svg/"}
	for _, name := range paths {
		// ValidPath 只检查虚拟路径语法，不检查名称对应的文件是否存在。
		fmt.Printf("%q valid=%t\n", name, fs.ValidPath(name))
	}
}

把校验放在 FS.Open 前面

如果名称来自请求参数、归档索引或用户配置，可以把校验集中在一个小函数里。返回错误时不要继续调用 Open；返回成功后再处理真实文件系统返回的 fs.ErrNotExist、权限错误或自定义 *fs.PathError。

package main

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

func openVirtualFile(fsys fs.FS, name string) (fs.File, error) {
	// 先挡住空段和点段，避免把不符合 FS 约定的名称交给实现层。
	if !fs.ValidPath(name) {
		return nil, fmt.Errorf("invalid virtual path %q", name)
	}

	file, err := fsys.Open(name)
	if err != nil {
		// 访问失败与名称非法是两类问题，保留底层错误供调用方判断。
		if errors.Is(err, fs.ErrNotExist) {
			return nil, fmt.Errorf("virtual file %q does not exist: %w", name, err)
		}
		return nil, err
	}
	return file, nil
}

真实业务里拿到文件后仍然要负责 Close。同时，ValidPath 通过不代表文件一定存在，也不代表任意自定义 FS 都已经完成了访问范围隔离；它只是先把输入放进 io/fs 约定的名字空间。

反斜杠通过，不等于可以当 Windows 路径使用

官方约定明确要求虚拟路径使用斜杠。反斜杠和冒号这样的字符本身可以被 ValidPath 接受，但 FS 实现不能把它们解释成路径分隔符。换句话说，assets\\logo.svg 可能是一个合法的单段虚拟文件名，不应先用 filepath.Clean 把它转换成宿主机路径，再拿结果回填到虚拟文件系统。

还要注意，语法合法不等于彻底的宿主机安全边界。os.DirFS、符号链接和自定义 FS 的访问语义，需要结合具体实现设计；如果目标是把访问限制在某个目录树，应采用对应的根目录能力和实现级约束，不能把 ValidPath 当作 chroot 替代品。

我会留下的判断清单

• 只验证虚拟名称时，调用 fs.ValidPath，不要用宿主机路径函数代替。
• 允许单独的 . 表示根目录；拒绝其他 .、..、空段以及首尾斜杠。
• 验证通过后再调用 FS.Open，把不存在、权限和实现错误分开处理。
• 不要把反斜杠或冒号自动解释成分隔符，也不要把语法检查误当成完整的目录隔离方案。

相关问题

fs.ValidPath(".") 为什么是 true？
因为在 io/fs 的统一路径语法中，单独的点表示根目录；a/./b 则包含点路径段，会被拒绝。

ValidPath 能检查文件是否存在吗？
不能。它只判断名称语法，文件是否存在要由 FS.Open、fs.Stat 等后续操作判断。