Go embed.FS 打开带 .. 的路径为什么会失败

把模板从本地目录迁移到 embed.FS 后，最容易遇到的一类故障是：磁盘路径明明能打开，换成 fs.Open("templates/../shared/header.html") 却返回错误。根因不是文件不存在，而是 embed.FS 使用 io/fs 的逻辑路径规则，.. 不能直接出现在传给 Open 的名字里。

官方地址：https://pkg.go.dev/embed#FS

先记住：embed.FS 里的路径不是操作系统文件路径。调用 Open 前，应该把外部拼接结果清理成以 / 分隔的相对逻辑路径；如果清理后仍会越过嵌入文件树根目录，就应该拒绝，而不是继续猜测。

影响面：为什么本地文件能读，embed.FS 却失败

迁移前，代码可能把目录作为根路径，再用操作系统的路径拼接函数生成真实文件名。磁盘文件系统会在访问时解释 . 和 ..，所以 templates/../shared/header.html 最终会落到 shared/header.html。

迁移到 embed.FS 后，调用对象变成了一个实现 fs.FS 的只读逻辑文件树。它接收的是资源名，不是任意操作系统路径。也就是说，文件实际存在并不能抵消资源名本身不合法。

时间线：故障通常发生在路径拼接之后

1. 模板加载器先收到一个相对模板名，例如 shared/header.html。
2. 为了复用目录前缀，调用方把它拼成 templates/../shared/header.html。
3. 磁盘版本正常工作，于是迁移代码保留了这个字符串。
4. embed.FS.Open 按 io/fs 的逻辑路径约束检查名字，在真正查找文件前返回路径错误。

排查时先打印“传入 Open 的最终字符串”，不要只打印期望的文件名。很多迁移问题不是嵌入声明漏了文件，而是中间层把合法的逻辑名重新拼成了带点段、绝对路径或反斜杠路径。

触发条件：Open 接收的不是任意文件路径

embed.FS 遵循 io/fs.ValidPath 的命名约束：普通资源名使用正斜杠分隔，不能以斜杠开头，不能包含空元素、. 或 .. 段。根目录用单独的 . 表示。

这也解释了几个看似相近的输入：

修复动作：在 Open 前清理并守住嵌入根目录

修复的关键不是把所有输入无条件替换成“看起来能打开”的字符串，而是在边界处完成三件事：拒绝不支持的分隔符，使用 path.Clean 归并合法的点段，最后用 fs.ValidPath 做一次逻辑路径检查。

package templates

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

// cleanEmbedName 把外部模板名转换为 embed.FS 可接受的逻辑路径。
func cleanEmbedName(raw string) (string, error) {
	// 嵌入文件树只使用 /；不把 Windows 反斜杠静默改写，避免隐藏调用方错误。
	if raw == "" || strings.Contains(raw, "\\") {
		return "", fmt.Errorf("invalid embedded path: %q", raw)
	}

	cleaned := path.Clean(raw)
	// 清理后仍以 .. 开头，说明输入试图越过嵌入文件树的根目录。
	if cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, "/") {
		return "", fmt.Errorf("path escapes embedded root: %q", raw)
	}
	// 这里再次检查逻辑路径规则，避免未来修改清理逻辑后放入非法名字。
	if !fs.ValidPath(cleaned) {
		return "", fmt.Errorf("path is not a valid fs path: %q", cleaned)
	}
	return cleaned, nil
}

对于 templates/../shared/header.html，path.Clean 会得到 shared/header.html，它可以通过 fs.ValidPath。但对于 ../../secret.html，清理结果仍然以 .. 开头，函数会在打开前拒绝。

把清理函数放到资源加载边界

路径清理完成后，再把结果交给嵌入文件系统。这样调用方不会在不同的加载分支里各自解释点段，错误也能保留原始输入，便于定位是哪一层把路径拼错了。

package templates

import (
	"embed"
	"fmt"
	"io"
)

//go:embed templates shared
var files embed.FS

// ReadTemplate 只接受嵌入文件树中的逻辑路径。
func ReadTemplate(name string) ([]byte, error) {
	cleaned, err := cleanEmbedName(name)
	if err != nil {
		return nil, err
	}

	// Open 使用清理后的逻辑名；这里不再调用 filepath.Join。
	f, err := files.Open(cleaned)
	if err != nil {
		return nil, fmt.Errorf("open embedded template %q: %w", name, err)
	}
	defer f.Close()

	data, err := io.ReadAll(f)
	if err != nil {
		return nil, fmt.Errorf("read embedded template %q: %w", name, err)
	}
	return data, nil
}

这里的重点是把 filepath.Join 换成适合逻辑路径的 path.Clean。filepath 会根据当前操作系统选择分隔符，而 io/fs 的路径约定与操作系统无关，统一使用 /。

防复发：用边界表覆盖迁移后的输入

路径问题最适合用一张小表固定预期，而不是等某个模板在生产环境第一次走到异常分支。测试至少覆盖：普通路径、同层级点段、越过根目录、绝对路径、空字符串和反斜杠。

func TestCleanEmbedName(t *testing.T) {
	tests := []struct {
		name string
		want string
		ok   bool
	}{
		// 同层级点段可以被归并到合法的逻辑路径。
		{name: "templates/../shared/header.html", want: "shared/header.html", ok: true},
		{name: "shared/header.html", want: "shared/header.html", ok: true},
		// 越过根目录、绝对路径和反斜杠必须被拒绝。
		{name: "../../secret.html", ok: false},
		{name: "/shared/header.html", ok: false},
		{name: `templates\\header.html`, ok: false},
	}

	for _, test := range tests {
		got, err := cleanEmbedName(test.name)
		if (err == nil) != test.ok {
			t.Fatalf("cleanEmbedName(%q) error = %v, want ok=%v", test.name, err, test.ok)
		}
		if err == nil && got != test.want {
			t.Fatalf("cleanEmbedName(%q) = %q, want %q", test.name, got, test.want)
		}
	}
}

结论：把磁盘路径思维换成逻辑资源名

这次故障的根因是路径语义发生了变化：磁盘文件系统会在访问时解释点段，而 embed.FS 要求调用方先提交符合 io/fs 规则的逻辑路径。迁移时只替换文件系统对象、不调整路径边界，就会留下“本地能读、嵌入后失败”的错觉。

实际项目中，把路径清理集中到资源加载入口，使用 path 而不是 filepath，对越过根目录和不支持的分隔符明确报错，再用表格测试固定边界，后续新增模板目录时就不容易重复踩坑。

常见问题

为什么不直接把 .. 替换成空字符串？

字符串替换会改变路径语义，可能把相邻目录拼成另一个名字。应让 path.Clean 按路径段处理，再检查结果是否仍越过嵌入根目录。

可以用 filepath.Clean 代替 path.Clean 吗？

不建议。embed.FS 遵循的是统一的正斜杠逻辑路径，filepath 会把当前操作系统的分隔符带入清理结果，容易让跨平台行为不一致。

fs.ValidPath 通过就一定能打开文件吗？

不一定。它只说明名字符合逻辑路径规则，文件是否真的被 go:embed 纳入、是否是目录以及资源是否存在，还要由 Open 的结果决定。