Go fs.ValidPath 构造嵌入资源路径的规则

fs.ValidPath 判断的不是宿主机路径，而是传给 fs.FS.Open、fs.ReadFile 等接口的虚拟文件系统名称。合法名称必须是 UTF-8、非根式、用正斜杠分隔；不能有空段、. 段或 .. 段，唯一例外是字符串 "." 可以单独表示文件树根目录。

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

Go embed 官方文档：https://pkg.go.dev/embed

五条规则就能判断 ValidPath

fs.ValidPath(name) 的规则可以压缩成五条：

1. 名称必须是有效 UTF-8。
2. 名称不能是绝对路径，开头不能有 /。
3. 统一用正斜杠 / 分隔，末尾也不能有斜杠。
4. 任何路径元素都不能是空字符串、. 或 ..。
5. 整个名称只有一个 . 时，表示文件树根目录，是合法特例。

下面这组值覆盖最常见的边界：

package main

import (
	"fmt"
	"io/fs"
)

func main() {
	// 同时列出根目录、普通资源名和几类非法点段
	names := []string{
		".",
		"assets/logo.svg",
		"",
		"/assets/logo.svg",
		"assets/",
		"assets//logo.svg",
		"assets/./logo.svg",
		"assets/../logo.svg",
	}

	// ValidPath 只判断 io/fs 名称语法，不访问实际文件
	for _, name := range names {
		fmt.Printf("%q => %t\n", name, fs.ValidPath(name))
	}
}

对应判断为：

"." => true
"assets/logo.svg" => true
"" => false
"/assets/logo.svg" => false
"assets/" => false
"assets//logo.svg" => false
"assets/./logo.svg" => false
"assets/../logo.svg" => false

反斜杠和冒号为什么可能返回 true

io/fs 在所有系统上都把 / 作为唯一分隔符。官方文档特别说明，反斜杠和冒号等字符可以出现在合法名称中，但文件系统实现绝不能把它们解释为路径分隔符。因此：

这也是不能用 filepath.Join 构造 embed.FS 名称的原因。filepath 遵循宿主操作系统分隔符，而 io/fs 要求可移植的斜杠语法。若最终确实要把合法的 io/fs 名称转换为本地路径，可在文件系统边界使用 filepath.Localize；嵌入资源内部则保持正斜杠。

运行时资源名和 go:embed 模式不是一回事

//go:embed 后面写的是编译期匹配模式，可以包含 * 等 path.Match 语法；embed.FS.Open 或 fs.ReadFile 接收的是已经确定的运行时名称，不能把通配模式当文件名。

package assets

import "embed"

// assets 目录在编译期递归嵌入；模式相对当前包目录解释
//go:embed assets
var content embed.FS

func ReadLogo() ([]byte, error) {
	// 运行时必须传明确的 io/fs 名称，不能传 assets/*.svg
	return content.ReadFile("assets/logo.svg")
}

两套规则有相似之处：都使用正斜杠，都不接受普通的 .、.. 或空路径元素。但编译期模式还要求至少匹配一个文件或非空目录，并受模块边界、符号链接和特殊文件名限制；fs.ValidPath 只做名称语法判断，不检查资源是否真的存在。

受信任片段用 path.Join 构造

当各片段都由程序固定提供时，使用 path.Join 可以稳定生成 io/fs 名称：

package assets

import (
	"io/fs"
	"path"
)

func readThemeFile(fsys fs.FS, theme, file string) ([]byte, error) {
	// path.Join 始终使用正斜杠，适合 io/fs 名称
	name := path.Join("assets", "themes", theme, file)

	// 在读取前保留最终语法检查，错误输入直接失败
	if !fs.ValidPath(name) {
		return nil, fs.ErrInvalid
	}
	return fs.ReadFile(fsys, name)
}

但 path.Join 会清理空段、. 和 ..。例如把 "assets"、"dark"、".."、"logo.svg" 拼接后，结果可能成为另一个看似合法的名称。若片段来自请求参数，先 Join 再 ValidPath 只能证明“清理后的结果合法”，不能证明原始输入没有越级意图。

外部输入先限制为单段，再拼接

对于“主题名 + 文件名”这种固定层级，最稳妥的方式是把每个外部值限制为单个名称元素。下面额外拒绝反斜杠和冒号，形成比 ValidPath 更严格、跨平台更直观的资源命名约定：

package assets

import (
	"fmt"
	"io/fs"
	"path"
	"strings"
)

func validAssetSegment(s string) bool {
	// 单段不能包含分隔符，也不接受容易和本地路径混淆的字符
	if strings.ContainsAny(s, `/\:`) {
		return false
	}

	// 对单段调用 ValidPath，可同时拒绝空串、点段和无效 UTF-8
	return fs.ValidPath(s)
}

func assetName(theme, file string) (string, error) {
	// 先验证原始输入，避免 path.Join 清理掉越级信息
	if !validAssetSegment(theme) || !validAssetSegment(file) {
		return "", fmt.Errorf("invalid asset segment: %w", fs.ErrInvalid)
	}

	// 片段都可信后再构造最终的嵌入资源名
	name := path.Join("assets", "themes", theme, file)
	if !fs.ValidPath(name) {
		return "", fs.ErrInvalid
	}
	return name, nil
}

如果业务允许用户提交多层相对路径，就不要先清理。可以先对原字符串执行 fs.ValidPath，再检查它是否位于允许的前缀或子文件系统中。fs.ValidPath 是语法门槛，不是授权系统；它不会判断某个合法名称是否应该对当前用户开放。

用 fs.Sub 把 assets 变成新的根

当所有调用都只访问 assets 子树时，可用 fs.Sub 减少重复前缀：

package assets

import (
	"embed"
	"io/fs"
)

// 编译期把 assets 子树放入只读嵌入文件系统
//go:embed assets
var content embed.FS

func readFromAssetRoot(name string) ([]byte, error) {
	// Sub 返回以 assets 为根的文件系统视图
	assetFS, err := fs.Sub(content, "assets")
	if err != nil {
		return nil, err
	}

	// 子树内仍然遵守 ValidPath；名称不再带 assets/ 前缀
	if !fs.ValidPath(name) {
		return nil, fs.ErrInvalid
	}
	return fs.ReadFile(assetFS, name)
}

fs.Sub 不改变路径语法，只改变文件系统视图的根。传入 "/logo.svg"、"../logo.svg" 仍然无效。还要注意，Sub 本身不承诺在创建视图时检查目录实际存在，真正读取时仍要处理 fs.ErrNotExist。

用表驱动测试固定边界

路径规则很短，最适合用表驱动测试锁住。测试重点不是资源是否存在，而是构造函数是否拒绝空段、分隔符和点段：

package assets

import "testing"

func TestAssetName(t *testing.T) {
	// 覆盖正常名称、父目录段、空段和反斜杠混淆
	tests := []struct {
		name  string
		theme string
		file  string
		want  string
		ok    bool
	}{
		{name: "normal", theme: "dark", file: "logo.svg", want: "assets/themes/dark/logo.svg", ok: true},
		{name: "parent", theme: "..", file: "logo.svg", ok: false},
		{name: "empty", theme: "", file: "logo.svg", ok: false},
		{name: "backslash", theme: `dark\admin`, file: "logo.svg", ok: false},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// 同时核对错误状态与成功时的最终资源名
			got, err := assetName(tt.theme, tt.file)
			if (err == nil) != tt.ok || got != tt.want {
				t.Fatalf("assetName() = %q, %v; want %q, ok=%v", got, err, tt.want, tt.ok)
			}
		})
	}
}

常见问题

fs.ValidPath 会检查文件是否存在吗？

不会。它只判断名称是否符合 io/fs 语法。存在性要通过 fs.Stat、fs.ReadFile 或 Open 的返回错误确认。

可以先 strings.TrimPrefix(name, "/") 再校验吗？

只有当开头斜杠是你明确设计的外部协议边界时才可以，例如把 URL 路径映射到资源名。不要对任意输入静默修复；应先确认固定前缀，再截取其后的相对名称并调用 fs.ValidPath。

为什么只有单独的点号合法？

io/fs 用 "." 统一表示文件树根目录。它不是普通名称元素，所以 "./a" 和 "a/." 仍然无效。

ValidPath 能防止 os.DirFS 中的符号链接逃逸吗？

不能。它只处理名称语法。Go 官方文档说明，os.DirFS 和 fs.Sub 不是 chroot 式安全边界，目录内部的符号链接仍可能指向外部；需要强约束本地文件访问时应使用专门的根目录隔离能力。