Go embed 怎样为嵌入文件设置可复用的 FS 根

我在把嵌入的模板和静态资源交给不同组件时，最容易遇到的不是 //go:embed 写错，而是每个调用方都记住了一遍目录前缀：模板用 web/templates，静态文件用 web/assets，通用读取函数又拼了一次 web/。更稳的做法是初始化阶段用 fs.Sub 建一个子文件系统，之后把它当成新的、可复用的 fs.FS 根。

一句话答案：如果变量 content 是一个 embed.FS，可以写 root, err := fs.Sub(content, "web")。创建成功后，root 中的 index.html 对应原来的 web/index.html，下游组件不必再知道 web 这个物理前缀。

官方地址：https://pkg.go.dev/io/fs#Sub

先判断问题是不是“根路径太深”

embed.FS 实现了 io/fs 的 fs.FS 接口。它保存的是嵌入目录树，所以直接读取时必须写出从嵌入根开始的相对路径。下面的目录关系只是为了说明路径契约：

web/
├── index.html
├── templates/
│   └── home.tmpl
└── assets/
    └── app.css

如果直接使用 content，应读取 web/index.html；如果把 web 变成新的根，则应读取 index.html。这两个写法不能混用。运行手册里先确认“当前对象的根是谁”，比盲目增加路径前缀更快。

用 fs.Sub 创建一个可复用的 FS 根

fs.Sub 属于 io/fs 包，返回的是对应目录子树的 fs.FS。创建动作适合放在包初始化或构造函数里，并把错误留在启动阶段处理：

package main

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

//go:embed web/*
var content embed.FS

func main() {
	// 只创建一次子根，让下游统一使用 web 内部的相对路径。
	webRoot, err := fs.Sub(content, "web")
	if err != nil {
		// 初始化失败时保留原始错误，避免把路径问题伪装成空文件。
		panic(fmt.Errorf("create embedded web root: %w", err))
	}

	// 子根下的 index.html 对应原始 FS 中的 web/index.html。
	data, err := fs.ReadFile(webRoot, "index.html")
	if err != nil {
		panic(fmt.Errorf("read embedded index: %w", err))
	}
	fmt.Println(len(data))
}

这段代码的关键不是把 fs.Sub 当作字符串拼接器，而是把“目录前缀”固化成一个新的文件系统对象。之后的函数只接收 fs.FS，就可以在不改调用方路径的情况下更换嵌入根或测试文件系统。

把子根交给模板和静态文件组件

一旦拿到 webRoot，模板解析和静态文件服务都可以直接使用它。这样做的判断信号是：下游组件本来就接受 fs.FS，而你只想让它看到某棵子树。

package webassets

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

//go:embed web/templates web/assets
var content embed.FS

// NewRoot 把物理目录 web 隐藏在一个稳定的 fs.FS 契约后面。
func NewRoot() (fs.FS, error) {
	// 调用方只需处理 index.html、templates/home.tmpl 等根内路径。
	root, err := fs.Sub(content, "web")
	if err != nil {
		return nil, fmt.Errorf("prepare web fs: %w", err)
	}
	return root, nil
}

func Handlers(root fs.FS) (http.Handler, *template.Template, error) {
	// FileServer 看到的是子根，不再要求请求路径带上 web 前缀。
	staticHandler := http.FileServer(http.FS(root))

	// 模板模式也以子根为起点，路径契约与静态资源保持一致。
	tmpl, err := template.ParseFS(root, "templates/*.tmpl")
	if err != nil {
		return nil, nil, fmt.Errorf("parse embedded templates: %w", err)
	}
	return staticHandler, tmpl, nil
}

这里的 root 是接口值，适合被传给多个只读消费者。要注意的是，http.FileServer 的 URL 前缀、反向代理的路径重写和文件系统根是三件事；使用子根只改变文件查找视角，不会自动替你配置外部 URL。

故障判断：目录不存在和路径写错不是一回事

fs.Sub 的文档明确说明，它不会检查目标目录当前是否存在。因此，创建子根成功并不等于后续的文件一定能读到。排查时按下面顺序判断：

读取文件时可以保留 fs.ErrNotExist 的判断，让告警区分“资源缺失”和其他 I/O 错误：

func readConfig(root fs.FS) ([]byte, error) {
	// 根内路径不带物理目录前缀，也不以斜杠开头。
	data, err := fs.ReadFile(root, "config/app.yaml")
	if err != nil {
		// 上层可以用 errors.Is 区分资源缺失与其他错误。
		return nil, fmt.Errorf("read config/app.yaml: %w", err)
	}
	return data, nil
}

如果根本没有目录，错误可能在第一次访问时才暴露；这也是为什么启动日志应记录“选择的子根名称”和“第一个关键资源读取结果”，而不是只记录 fs.Sub 已返回成功。

复用根时要保留哪些边界

“可复用”指的是多个消费者共享同一个 fs.FS 视角，不是把文件内容复制到多个变量里。实践中我会把根的创建和下游消费拆开：

func subRoot(fsys fs.FS, dir string) (fs.FS, error) {
	// 统一封装根创建，避免不同模块对 dir 的处理方式不一致。
	root, err := fs.Sub(fsys, dir)
	if err != nil {
		return nil, fmt.Errorf("sub root %q: %w", dir, err)
	}
	return root, nil
}

func loadTemplate(root fs.FS, name string) (*template.Template, error) {
	// name 约定为子根内路径，调用方不再传入物理父目录。
	tmpl, err := template.ParseFS(root, name)
	if err != nil {
		return nil, fmt.Errorf("load template %q: %w", name, err)
	}
	return tmpl, nil
}

保留两个根也很有用：一个是完整的 content，供需要全局目录视角的任务使用；另一个是 webRoot，供网站组件使用。不要为了“统一”而把所有调用方强行迁移到子根，先写清楚每个函数接受哪一种路径契约。

回滚路径：先恢复根，再恢复调用方路径

如果上线后出现模板找不到或静态资源 404，最快的回滚不是继续给路径加前缀，而是先恢复到发布前的对象边界：

1. 保留原始 content embed.FS，暂时让受影响组件继续使用完整根。
2. 把调用方恢复为带物理目录的路径，例如 web/templates/home.tmpl。
3. 确认 URL 路由层没有同时做一次相同的前缀剥离。
4. 再单独切回 fs.Sub，每次只迁移一个消费者。

复盘时记录三项就够：嵌入模式、暴露的 FS 根、下游约定的相对路径。它们分别对应“编译时收集了什么”“运行时从哪里看”“调用方传什么名字”，缺一项就容易重复拼接目录。

常见问题

fs.Sub 会复制嵌入文件吗？

不需要把文件内容重新复制一遍。它返回一个对应子树的 fs.FS 视角；对 embed.FS 来说，调用方得到的是路径根的包装。

把目录设置成子根后还能读取父目录吗？

不能通过根内的 .. 返回父级。子根的价值就是让下游只能按这棵子树的路径契约访问；需要父级时保留并传入原始 fs.FS。

fs.Sub 能不能当作安全沙箱？

对于 embed.FS 这类只读嵌入树，它适合整理路径边界；但官方文档明确提醒，针对操作系统目录的 fs.Sub 不等同于 chroot 式安全隔离。安全目标应选择专门的受限根能力。

最终可以记成一条运行手册：先确定完整根，再用 fs.Sub 固化一个子根，把这个 fs.FS 交给下游，最后用根内相对路径读取。出现错误时先判断“根选错”还是“资源没嵌入”，不要把两种问题混成字符串拼接问题。