Go embed.FS fs.Sub 如何暴露子目录

Go 的 embed.FS 保存的是一棵带目录前缀的只读文件树。比如把 web 目录嵌入后，首页原本叫 web/index.html；如果希望静态服务把 web/ 当成根目录，就用 fs.Sub(assets, "web") 创建一个新的文件系统视图。之后读取首页写 index.html，而不是再次写 web/index.html。

目录前缀与暴露根目录要分开理解

先假设项目里有这样的资源布局：

web/
  index.html
  static/
    app.js

嵌入目录后，assets 看到的是 web/、web/index.html 和 web/static/app.js。fs.Sub 不会改变磁盘目录，也不会复制字节，它只是返回一个把指定目录“抬到根部”的 fs.FS 视图。

最小写法：用 fs.Sub 把 web 目录抬到根部

标准库的 fs.Sub 接收一个 fs.FS 和目录名，返回子树或错误。下面的写法把错误留在初始化阶段处理，避免服务已经启动后才发现目录名称拼错。

package main

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

//go:embed web
var assets embed.FS

func main() {
	// 这里去掉 web 前缀，让 publicFS 的根直接对应 web/。
	publicFS, err := fs.Sub(assets, "web")
	if err != nil {
		// 目录不存在时立即停止，避免带着错误根目录继续运行。
		panic(err)
	}

	// 新根下使用 index.html；再次写 web/index.html 会多拼一层目录。
	data, err := fs.ReadFile(publicFS, "index.html")
	if err != nil {
		panic(err)
	}
	fmt.Println(len(data))
}

这里还要记住 fs.FS 的路径不是操作系统路径：使用 / 分隔，根目录写成 .，不要传入以 / 开头的绝对路径。若只想保留原始根目录，fs.Sub(assets, ".") 会返回原 FS。

把子文件系统交给 http.FileServer

嵌入静态站点时，常见目标是让浏览器访问 / 就能得到 web/index.html。关键是先做一次子树映射，再把映射后的 FS 交给 http.FS；否则 URL 根下仍然要携带 web/ 前缀。

publicFS, err := fs.Sub(assets, "web")
if err != nil {
	// 启动前确认嵌入目录存在，错误不向请求阶段扩散。
	log.Fatal(err)
}

// http.FS 适配 io/fs.FS，FileServer 负责按 URL 读取文件。
handler := http.FileServer(http.FS(publicFS))
http.Handle("/", handler)
log.Fatal(http.ListenAndServe(":8080", nil))

这段服务中，/ 对应子 FS 的根，/index.html 对应 web/index.html，/static/app.js 对应 web/static/app.js。如果你还使用 http.StripPrefix，要先明确它处理的是 URL 前缀，而 fs.Sub 处理的是文件系统目录前缀，两者不要重复裁剪。

发布前检查：路径、错误和资源边界

把这件事放进生产服务前，可以按三项检查。第一，确认 //go:embed web 紧邻 embed.FS 变量，目录确实位于当前包目录或子目录中。第二，在同一个子 FS 上用 fs.ReadDir(publicFS, ".") 看根目录是否出现 index.html 和 static，不要凭 URL 猜路径。第三，统一记录映射表，避免模板读取使用 index.html、静态服务却又拼成 web/static。

常见问题

为什么 fs.Sub 返回 no such file 或 PathError？

传入的目录名必须存在于原始 FS，且符合 io/fs 的有效路径规则。先用原始 assets 读取目录，再核对 //go:embed 的模式和包目录位置。

fs.Sub 会把文件从嵌入包复制出来吗？

不会。它提供的是新的 FS 视图，底层内容仍是只读嵌入资源；它解决的是路径根的表达，不是文件搬迁。

什么时候不需要 fs.Sub？

如果外部调用方本来就约定使用 web/index.html 这样的完整路径，直接使用 embed.FS 更简单。只有需要隐藏固定目录前缀、统一 HTTP 根路径或交给模板读取时，才值得建立子目录视图。

记住一句话即可：原始 embed.FS 负责保存目录树，fs.Sub 负责选择对外暴露的根。先确认新根下的相对路径，再接入读取函数或 HTTP 服务，绝大多数“明明嵌入了却找不到文件”的问题都会在启动阶段被定位。