Go embed.FS 怎么限制模板读取范围：子目录挂载、路径清理与上线验收

项目上线后，模板渲染突然开始报“找不到文件”，排查时却发现二进制里明明嵌入了模板。更容易踩中的另一侧问题是：为了省事把整个资源目录交给模板引擎，后来新增的说明文件、测试文件也被一起暴露。embed.FS 的关键不是“能不能嵌入”，而是挂载给业务代码的文件系统边界到底有多大。

先复现目录挂载过宽的问题

假设项目目录如下，templates/ 下既有正式页面，也有只供开发者查看的片段：

assets/
  templates/
    pages/home.html
    partials/header.html
    internal/debug.html
    testdata/sample.html

最省事的写法是把 assets 整棵树交给模板加载器。它确实能读到 templates/pages/home.html，但“能读到”不等于“应该让所有调用路径都能读到”。后续有人把模板名拼接进请求参数时，内部目录也可能被带入同一套读取逻辑。

用 fs.Sub 固定业务看到的根目录

先把嵌入声明放在资源目录的上一级，再显式切出 templates。这样模板加载器拿到的根已经不是项目资源根：

package view

import (
    "embed"
    "io/fs"
    "text/template"
)

//go:embed assets
var embedded embed.FS

func loadTemplate(name string) (*template.Template, error) {
    templates, err := fs.Sub(embedded, "assets/templates")
    if err != nil {
        return nil, err
    }
    return template.ParseFS(templates, name)
}

func mainTemplate() (*template.Template, error) {
    return loadTemplate("pages/home.html")
}

fs.Sub 返回的是一个新的、以目标目录为根的文件系统。后续代码只需要处理 pages/home.html 这样的相对名字，不必在每个调用点重复写资源前缀。这里不要把 fs.Sub 的错误吞掉；目录名拼错时，尽早失败比运行到页面请求才发现更容易定位。

路径清理不是权限校验

如果模板名来自路由或配置，先清理路径只能解决一部分输入问题。path.Clean 会把路径规范化，但不会替你判断它是否属于允许的目录。一个小的白名单函数更直观：

func safeTemplateName(input string) (string, error) {
    name := path.Clean("/" + input)
    name = strings.TrimPrefix(name, "/")
    if name == "." || !strings.HasPrefix(name, "pages/") {
        return "", fmt.Errorf("template outside pages: %q", input)
    }
    if strings.Contains(name, "..") {
        return "", fmt.Errorf("invalid template path: %q", input)
    }
    return name, nil
}

更稳妥的做法是把可渲染页面注册成有限映射，例如只允许 home、help 映射到固定文件名。这样调用方根本没有机会提交任意文件路径。无论采用哪种方式，测试都要覆盖空字符串、绝对路径、连续点号和不存在文件。

把三类验收写成测试

上线前至少确认三件事：正式模板能读、目录边界没有被绕过、构建产物确实包含资源。可以先用 fs.ReadFile 做轻量验收：

func TestTemplateBoundary(t *testing.T) {
    templates, err := fs.Sub(embedded, "assets/templates")
    if err != nil {
        t.Fatal(err)
    }

    if _, err := fs.ReadFile(templates, "pages/home.html"); err != nil {
        t.Fatalf("home template missing: %v", err)
    }
    if _, err := fs.ReadFile(templates, "../internal/debug.html"); err == nil {
        t.Fatal("internal file unexpectedly readable")
    }
}

再跑一次实际模板解析测试，避免文件存在但模板语法已经损坏。部署检查则应使用最终构建命令生成的二进制或容器镜像，不能只在源码目录里运行测试就宣布通过。

几个看似方便的写法为什么会留下坑

• 把整个 embed.FS 传到很多包：任何包都能自行决定读取范围，边界不可追踪。
• 只调用 path.Clean：规范化路径不等于授权，仍需要目录约束或固定映射。
• 测试只覆盖首页：新增模板、错误页和不存在文件的行为没有被验证。
• 把开发样例放进生产嵌入目录：即使当前没有入口，后续重构也可能误加载。

排查结束后的落地清单

实际项目里，我更建议把资源目录按用途拆开：模板、静态资源和测试样例各自独立；每个加载器在创建时完成 fs.Sub；外部输入只经过固定映射；CI 运行合法、越界和缺失文件三组测试。这样出现“文件找不到”时，日志能直接告诉你是嵌入失败、子目录配置错误，还是调用方传入了不允许的名字。

相关问题

embed.FS 能读取运行时后来新增的模板吗？

不能。它把匹配到的文件编译进程序，运行时文件变化不会自动进入这个文件系统。需要热更新时，应明确使用磁盘文件系统或开发环境专用加载器。

为什么生产环境应该保留嵌入目录的最小范围？

最小范围更容易审计，也能降低误把调试资料、测试样例或内部说明当成可渲染资源的风险。

总结

embed.FS 解决的是资源随二进制发布，不是自动完成访问控制。先用 fs.Sub 固定根，再对模板名做白名单或边界校验，最后用构建产物完成正反向测试，模板目录的“能读”和“该读”才能真正分开。