直接用http.FileServer会404，因其仅做字面路径映射，不自动查找index.html、不处理目录斜杠、不支持SPA fallback；需用IndexFileSystem包装实现index fallback，或自定义Handler做SPA兜底，embed.FS则必须经http.FS转换才能使用。
为什么直接用 net/http.FileServer 会返回 404？
常见现象是：你写了 http.Handle("/", http.FileServer(http.Dir("./static")))，但访问 /index.html 正常，/ 却 404。这是因为 http.FileServer 默认不自动查找 index.html，且对路径末尾斜杠处理严格——/ 被当作目录请求，而 Go 的默认 FileSystem 实现不自动追加斜杠或 fallback 到 index.html。
根本原因在于 http.Dir 返回的 http.FileSystem 实现只做字面路径映射，不包含任何路由逻辑或 index fallback 行为。
- 若请求路径是
/，它会尝试打开当前目录（即"./static/"），但不会进一步检查是否存在index.html - 若请求路径是
/foo且./static/foo不存在，但./static/foo/index.html存在，它也不会自动重写或查找 - 所有路径都区分大小写，且不支持通配符或 SPA 的 fallback（比如 React Router 的
404 → index.html）
如何让 http.FileServer 支持自动 index.html？
Go 标准库没提供开关，但你可以包装一层 http.FileSystem，在 Open 方法中手动处理 index fallback。核心思路是：当原路径打开失败时，尝试拼接 /index.html 并再次打开。
注意：必须先调用 fs.Open(path)，再判断错误类型；不能直接预判路径是否存在，因为 http.Dir 内部可能有符号链接、权限限制等复杂情况。
type IndexFileSystem struct {
fs http.FileSystem
}
<p>func (i IndexFileSystem) Open(path string) (http.File, error) {
f, err := i.fs.Open(path)
if err == nil {
return f, nil
}
// 如果是 os.IsNotExist 错误，且 path 是目录形式（以 / 结尾），尝试 index.html
if os.IsNotExist(err) && strings.HasSuffix(path, "/") {
indexPath := path + "index.html"
if f2, err2 := i.fs.Open(indexPath); err2 == nil {
return f2, nil
}
}
return f, err
}</p><p>// 使用方式：
http.Handle("/", http.FileServer(IndexFileSystem{http.Dir("./static")}))
如何实现 SPA fallback（如 React/Vue 路由）？
单页应用需要把所有非静态资源请求（如 /user/123）也返回 index.html，否则前端路由无法工作。这已超出 FileSystem 职责，必须在 handler 层拦截。
不要试图修改 FileSystem.Open 来做 fallback —— 它只应负责“读文件”，不该决定“该返回哪个文件”。正确做法是自定义 http.Handler，先尝试用 FileServer 服务，失败后再返回 index.html。
- 用
httptest.NewUnstartedServer或临时ResponseWriter捕获FileServer的响应状态码不可靠，容易出错 - 推荐做法：用
http.StripPrefix+ 手动stat判断路径是否存在（注意：仅适用于真实文件系统，不适用于嵌入的embed.FS） - 更健壮的做法是提前构建白名单（如
.js,.css,.png等扩展名），其余全部 fallback
示例（基于扩展名白名单）：
func spaHandler(fs http.FileSystem) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
path := r.URL.Path
// 先尝试原路径
f, err := fs.Open(path)
if err == nil {
http.ServeContent(w, r, path, time.Now(), f)
return
}
// 否则检查是否为静态资源扩展名，不是就 fallback
ext := strings.ToLower(filepath.Ext(path))
if ext == "" || !strings.Contains(",.js,.css,.png,.jpg,.woff2,.svg,", ext) {
f, _ = fs.Open("/index.html")
http.ServeContent(w, r, "/index.html", time.Now(), f)
return
}
http.Error(w, err.Error(), http.StatusNotFound)
})
}
<p>http.Handle("/", spaHandler(http.Dir("./dist")))
使用 embed.FS 时为什么 http.FileServer 不生效？
因为 embed.FS 不是 http.FileSystem 接口的实现，它缺少 Open 方法。直接传给 http.FileServer 会编译报错：cannot use embedded (type embed.FS) as type http.FileSystem。
解决方案是用 http.FS 包装：它是标准库提供的适配器，将 embed.FS 转为 http.FileSystem。
-
http.FS是函数，不是类型；它接受fs.FS（即embed.FS实现的接口），返回http.FileSystem - 注意路径前缀：嵌入的文件路径是相对于
//go:embed指令所在目录，http.FS不会自动 strip 前缀 - 如果嵌入的是子目录（如
//go:embed static/*），则http.FS(embededFS)中的路径需带static/前缀
正确用法：
//go:embed static/*
var staticFiles embed.FS
<p>func main() {
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(staticFiles))))
}
这里 http.FS(staticFiles) 把 embed.FS 转成可用的 FileSystem，而 http.StripPrefix 是为了去掉 URL 中的 /static/ 前缀，让内部路径匹配嵌入结构。
嵌入文件路径和运行时 URL 路径的映射关系最容易被忽略——多一层目录、少一个斜杠，都会导致 404，而且没有明显错误提示。
