Go embed.FS怎样把模板资源嵌入并按目录读取怎样完成一个可复用的最小示例

如果模板、邮件片段或静态页面需要随 Go 程序一起交付，最小而稳妥的做法是用 embed.FS 把目录编译进二进制，再把它当作 fs.FS 交给读取函数或模板解析器。这样部署时不必再复制一份模板目录，但资源变更也必须重新构建。

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

本文只解决一个具体任务：把 templates/ 目录嵌入程序，按目录读取模板，并用 html/template 渲染一个页面。示例中的路径、错误和目录边界都保留在代码里，方便直接改成自己的服务。

先把模板目录嵌入成一个可读取的文件系统

先约定目录结构。源文件与模板目录放在同一个 Go 包目录下，//go:embed 的匹配模式就以这个包目录为基准：

web/
├── embed.go
└── templates/
    ├── layout.html
    └── pages/
        └── home.html

然后在包级别声明 embed.FS。指令必须紧挨着变量声明，不能放进函数，也不能把它写成运行时才赋值的局部变量。

package web

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

// 模板资源在构建时从当前包目录嵌入程序。
//go:embed templates
var templateFS embed.FS

// listTemplates 用于读取模板目录，错误会交给调用方处理。
func listTemplates() ([]string, error) {
	entries, err := fs.ReadDir(templateFS, "templates")
	if err != nil {
		return nil, fmt.Errorf("读取模板目录失败: %w", err)
	}

	names := make([]string, 0, len(entries))
	for _, entry := range entries {
		// 这里只列出目录项；子目录是否递归由后续解析策略决定。
		names = append(names, entry.Name())
	}
	return names, nil
}

这里的 templates 是嵌入树的根。目录模式会递归匹配子目录，但以点号或下划线开头的文件有特殊排除规则；如果确实要纳入这类文件，要单独评估 all: 前缀是否符合发布要求。

ReadDir 和 ReadFile 分别负责目录与文件

embed.FS 实现了 fs.FS，因此可以用标准库的 fs.ReadDir、fs.ReadFile 读取它。路径使用斜杠，并且是相对于嵌入文件系统根目录的路径。

package web

import (
	"fmt"
	"io/fs"
)

// readHomeTemplate 只读取一个明确的模板文件，适合启动时预加载。
func readHomeTemplate() ([]byte, error) {
	data, err := fs.ReadFile(templateFS, "templates/pages/home.html")
	if err != nil {
		// 保留原始错误，调用方可以用 errors.Is 判断路径是否不存在。
		return nil, fmt.Errorf("读取首页模板失败: %w", err)
	}
	return data, nil
}

如果需要用 templateFS.ReadFile，结果是一样的；使用 fs.ReadFile 的好处是函数参数直接体现了 fs.FS 抽象，未来可以替换为测试文件系统或其他只读实现。

目录读取和文件读取的路径不要混用：把目录传给 ReadFile 会得到错误，把文件传给 ReadDir 也不会自动替你推断父目录。生产代码应该在错误信息里带上具体路径，避免发布后只能看到笼统的“模板失败”。

用 fs.Sub 把模板根目录交给解析器

如果每次都写 templates/ 前缀，解析代码会被资源目录结构绑住。可以先用 fs.Sub 得到只包含模板子树的文件系统，再让后续代码只处理相对路径。

package web

import (
	"fmt"
	"io/fs"
)

// templateTree 把资源根目录收窄为模板子树，避免调用方重复拼接前缀。
func templateTree() (fs.FS, error) {
	sub, err := fs.Sub(templateFS, "templates")
	if err != nil {
		return nil, fmt.Errorf("创建模板子树失败: %w", err)
	}
	return sub, nil
}

得到的 sub 仍是 fs.FS。此时 pages/home.html 可以被直接读取，而不再需要写成 templates/pages/home.html。这一步只是改变观察根，不会把资源变成可写目录，也不会复制一份文件。

把子树交给 html/template 并保留错误边界

html/template 能直接消费实现 fs.FS 的对象。常见的生产写法是：先获得子树，再解析模板；解析失败时不要写入半截响应，执行失败则返回错误或交给统一错误处理。

package web

import (
	"fmt"
	"html/template"
	"io/fs"
	"net/http"
)

// renderHome 解析嵌入模板并写入响应，模板错误不会被静默吞掉。
func renderHome(w http.ResponseWriter, data any) error {
	sub, err := fs.Sub(templateFS, "templates")
	if err != nil {
		return fmt.Errorf("创建模板子树失败: %w", err)
	}

	// 模式相对 sub 根目录，避免把物理目录前缀暴露给调用方。
	tmpl, err := template.ParseFS(sub, "layout.html", "pages/home.html")
	if err != nil {
		return fmt.Errorf("解析首页模板失败: %w", err)
	}
	if err := tmpl.ExecuteTemplate(w, "home", data); err != nil {
		return fmt.Errorf("渲染首页失败: %w", err)
	}
	return nil
}

模板文件里的定义名称要和 ExecuteTemplate 使用的名称一致；如果没有显式定义，可以改用 Execute 并确认解析得到的根模板就是预期文件。无论选择哪一种，都应该保留解析错误和执行错误的上下文。

四个容易踩到的边界

还要注意，embed.FS 是只读文件系统，适合内置模板、静态页面和邮件片段，不适合保存用户上传文件。上传文件应使用明确的外部存储，并通过接口把它交给业务层。

最小复用清单

1. 让 //go:embed 紧挨包级的 embed.FS 变量，并确认模式覆盖实际模板目录。
2. 需要枚举时用 ReadDir，需要单文件时用 ReadFile，错误里保留具体路径。
3. 解析器不需要知道资源物理前缀时，用 fs.Sub 暴露更小的模板根。
4. 把解析错误和执行错误分开处理，避免把半截 HTML 当作成功响应。
5. 把模板作为发布物管理：资源变化要重新构建，运行时不要尝试写入 embed.FS。

如果你的需求只是嵌入一个固定文件，string 或 []byte 变量可能比 embed.FS 更简单；当资源有目录结构、需要交给 html/template 或其他 fs.FS 消费者时，再选择 embed.FS 更合适。