embed.FS 与 fs.Sub 组合静态资源服务

把前端静态文件随 Go 二进制发布时，常见做法是用 //go:embed 得到一个 embed.FS，再交给 net/http 的文件服务处理。真正容易出错的地方不在嵌入本身，而在目录前缀：嵌入变量看到的是完整树，路由通常只希望从某个子目录开始。

fs.Sub 负责裁剪嵌入文件系统的目录视图，http.FS 负责把通用的 fs.FS 转成 HTTP 文件系统，StripPrefix 负责移除 URL 前缀。三者组合后，浏览器请求路径就能稳定映射到二进制中的静态文件。

官方文档地址：https://pkg.go.dev/embed、https://pkg.go.dev/io/fs、https://pkg.go.dev/net/http。

先看 embed.FS 的目录视图

假设项目中有这样的资源目录：

web/
├── index.html
├── static/
│   ├── css/app.css
│   └── js/app.js

使用 //go:embed web 后，嵌入文件系统中的名字仍然带着 web/ 前缀。也就是说，读取首页时要使用 web/index.html，读取样式时要使用 web/static/css/app.css。embed.FS 实现了 io/fs.FS，它是一棵只读文件树，可以交给支持 fs.FS 的标准库组件。

用 fs.Sub 裁剪资源根目录

fs.Sub(fsys, "web") 返回以 web 为根的新文件系统。裁剪之后，服务层读取 index.html 就等价于读取原树中的 web/index.html，读取 static/css/app.css 就等价于读取 web/static/css/app.css。这样可以把构建目录名称隔离在资源装配层，避免它泄漏到 HTTP 路径和模板引用中。

fs.Sub 只改变访问视图，不复制文件，也不会把资源写回磁盘。它返回错误的主要原因是子目录参数不符合文件系统要求或底层文件系统拒绝访问；目录不存在本身不一定在调用 Sub 时立刻报错，真正打开文件时仍要处理错误。

package main

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

//go:embed web
var embeddedFiles embed.FS

func assetTree() (fs.FS, error) {
	// 把构建目录从服务层路径中隐藏，只暴露 web 目录下的内容。
	staticFS, err := fs.Sub(embeddedFiles, "web")
	if err != nil {
		// 目录配置错误应在启动阶段暴露，而不是等首个请求才发现。
		return nil, fmt.Errorf("裁剪静态资源目录: %w", err)
	}
	return staticFS, nil
}

用 http.FS 接入 FileServer

http.FileServer 接收的是 http.FileSystem，而 fs.Sub 返回的是通用 fs.FS。http.FS 就是两者之间的适配器：它把文件树转换为 HTTP 文件服务能够打开和读取的形式。

这一步仍然没有启动服务器，也没有访问本地磁盘。传入的是裁剪后的只读嵌入树，因此发布后的二进制可以在没有前端资源目录的环境中提供文件。若希望服务目录中的 index.html，FileServer 会按 HTTP 文件服务规则处理目录请求。

func staticHandler() (http.Handler, error) {
	staticFS, err := assetTree()
	if err != nil {
		return nil, err
	}

	// http.FS 把 io/fs 的只读文件树适配成 FileServer 所需的接口。
	return http.FileServer(http.FS(staticFS)), nil
}

组合 URL 前缀与 StripPrefix

假设对外约定静态资源都从 /assets/ 开始，而裁剪后的文件树从 css/、js/ 开始，那么请求 /assets/css/app.css 到达文件服务前必须先变成 /css/app.css。http.StripPrefix("/assets/", handler) 正好承担这一步。

注意三个名称不要混为一谈：/assets/ 是 URL 路由前缀，web 是嵌入树中的目录名，css/app.css 是裁剪后文件系统中的相对路径。StripPrefix 只处理 URL，不会修改 embed.FS 的内容。

package main

import (
	"log"
	"net/http"
)

func main() {
	static, err := staticHandler()
	if err != nil {
		// 静态目录配置属于启动依赖，失败时直接终止比静默提供空目录更安全。
		log.Fatal(err)
	}

	mux := http.NewServeMux()
	// 先移除 /assets/，再让 FileServer 从裁剪后的根目录查找文件。
	mux.Handle("/assets/", http.StripPrefix("/assets/", static))

	// 这里的端口只是示例；生产环境可交给已有的监听与优雅退出流程。
	log.Fatal(http.ListenAndServe(":8080", mux))
}

把目录和 URL 映射成一条可检查的链

可以用下面的顺序检查资源是否接对：

1. 嵌入层：//go:embed web 是否覆盖了目标目录，资源是否确实位于构建上下文中。
2. 裁剪层：fs.Sub(embeddedFiles, "web") 后，服务层是否应该从 index.html 或 static/ 开始寻找文件。
3. 适配层：是否把裁剪后的 fs.FS 传给了 http.FS，而不是误把原始磁盘路径传给服务端。
4. 路由层：Handle 的模式、StripPrefix 的前缀和浏览器实际请求的前缀是否完全一致，尤其要注意末尾斜杠。
5. 文件层：请求路径去掉 URL 前缀后，是否能在裁剪后的树中找到同名文件；引用路径多一层 web/ 就会变成找不到。

常见误区与发布边界

误区一：把 fs.Sub 当成复制目录。它只是返回一个子树视图，嵌入资源依旧是只读的。若程序需要上传、编辑或生成文件，应另行设计可写存储。

误区二：StripPrefix 写成文件系统路径。它匹配的是 HTTP 请求路径，应该使用 /assets/ 这样的 URL 前缀，而不是 web 或操作系统路径。

误区三：只改 Handler，不改前端引用。如果 HTML 仍引用 /web/static/app.css，而路由只暴露 /assets/，两边依然不匹配。建议在构建配置中统一资源公共前缀。

误区四：把嵌入当成动态目录。每次重新发布都要重新编译才能更新文件；缓存头、压缩策略和版本化文件名仍应由 HTTP 层或构建流程负责。

常见问题与速查表

最终可以把组合关系记成一句话：embed.FS 保存资源，fs.Sub 整理资源根，http.FS 完成接口适配，StripPrefix 对齐 URL 前缀，http.FileServer 负责读取并返回文件。把这五个职责分开，静态资源服务就不容易因目录层级变化而失控。