Go embed.FS 怎样把内嵌静态文件挂到 HTTP 子路径

把静态页面编进 Go 二进制后，最容易出错的不是 //go:embed，而是“文件系统里的路径”和“HTTP 对外暴露的路径”没有对齐。一个稳定的组合是：先用 fs.Sub 把内嵌目录切成服务根，再用 http.FS 适配文件系统，最后用 http.StripPrefix 去掉公开的 /assets/ 前缀。

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

如果代码目录是 web/index.html，而访问地址想写成 /assets/index.html，就让 fs.Sub 负责隐藏 web 目录层，让 StripPrefix 负责隐藏 URL 的 /assets/ 层。两次“去掉一层”分别属于文件系统和 HTTP 路由，不能混为一谈。

先把内嵌目录和 URL 目标写清楚

假设项目中有下面的资源：

web/
  index.html
  assets/
    app.css
    app.js

//go:embed web 得到的 embed.FS 里，根节点仍然包含 web。也就是说，原始虚拟路径是 web/index.html，不是 index.html。如果期望客户端访问 /assets/index.html，服务端需要同时处理两种前缀：

用 fs.Sub 把 web 目录切成服务根

fs.Sub 返回一个新的文件系统视图。它不复制文件，也不改变嵌入内容，只是把指定目录作为新的根。这样 http.FileServer 查找 /index.html 时，实际对应的就是内嵌资源 web/index.html。

package main

import (
	"embed"
	"io/fs"
	"log"
	"net/http"
)

// embedded 保存 web 目录及其子目录，资源会在编译时进入二进制。
//go:embed web
var embedded embed.FS

func main() {
	// 把 web 切成新的根，避免把项目中的其他嵌入目录暴露给 HTTP。
	staticFiles, err := fs.Sub(embedded, "web")
	if err != nil {
		log.Fatal(err)
	}

	// http.FS 把通用 fs.FS 适配成 FileServer 能读取的文件系统。
	fileHandler := http.FileServer(http.FS(staticFiles))

	// 对外保留 /assets/，交给 FileServer 的路径从 /index.html 开始。
	http.Handle("/assets/", http.StripPrefix("/assets/", fileHandler))

	log.Fatal(http.ListenAndServe(":8080", nil))
}

这里的关键不是把三个函数机械串起来，而是确认每个函数只承担一层职责：fs.Sub 处理内嵌目录，http.FS 处理接口转换，FileServer 根据请求路径查文件。

用 StripPrefix 让 HTTP 子路径和文件查找对齐

当请求是 /assets/index.html 时，StripPrefix 会把传给下游 Handler 的 URL 路径视图改为 /index.html。因此下游的 FileServer 不需要知道外部路由叫 /assets/，只需要面对已经切好的 staticFiles 根。

如果漏掉 StripPrefix，FileServer 就会尝试在嵌入根中寻找 assets/index.html；如果同时又用 fs.Sub(embedded, "web")，这个路径通常并不存在。反过来，如果只用 StripPrefix 而不做 fs.Sub，FileServer 看到的 /index.html 也无法对应原始的 web/index.html。

几个容易忽略的边界

路由模式要带尾斜杠

通常应注册 /assets/，而不是只注册 /assets。这样目录资源的相对路径和 FileServer 的目录重定向行为更容易保持一致。页面中引用 CSS、JavaScript 或图片时，也要使用与部署前缀匹配的路径，不能假定站点一定挂在根路径。

不要把项目根直接暴露出去

如果整个 embed.FS 还包含模板、配置样例或其他内部文件，直接交给 http.FileServer(http.FS(embedded)) 会让这些目录进入可访问范围。先用 fs.Sub 切到专门的静态目录，是更清晰的边界。

目录索引不是前端路由回退

FileServer 能处理目录和默认索引文件，但它不会自动把所有未知路径回退到单页应用的 index.html。如果项目需要前端路由回退，应额外设计 Handler，并明确哪些资源可以回退；不要把这项行为误认为 StripPrefix 的职责。

一份可复用的最小组合

需要把静态资源挂到任意子路径时，可以保持下面这个顺序。变量名可以换，职责顺序不要换：

// 只展示组合关系：内嵌目录、文件系统视图、HTTP 适配和公开前缀各自独立。
staticFiles, err := fs.Sub(embedded, "web")
if err != nil {
	// 启动阶段无法得到静态根时直接终止，避免服务启动后再返回大量 404。
	log.Fatal(err)
}

staticHandler := http.FileServer(http.FS(staticFiles))

// /assets/index.html 会被映射到静态根中的 /index.html。
mux.Handle("/assets/", http.StripPrefix("/assets/", staticHandler))

速记就是：目录用 fs.Sub，接口用 http.FS，URL 前缀用 StripPrefix，文件查找交给 FileServer。只要能分别说出这四个组件处理的是哪一层，内嵌静态文件挂载到 HTTP 子路径的问题就不会再靠试 URL 猜。

相关问题

• 为什么不能只写 http.FileServer(http.FS(embedded))？ 因为嵌入根通常还包含 web 目录层，公开路径和虚拟文件路径未必相同。
• fs.Sub 会复制资源吗？ 不会，它提供的是以指定目录为根的文件系统视图。
• StripPrefix 会修改磁盘或嵌入文件吗？ 不会，它只改变下游 Handler 看到的请求路径。
• 静态文件一定要叫 assets 吗？ 不需要，assets 只是公开 URL 前缀示例，内嵌目录和路由前缀可以按项目约定命名。