Go http.FileServer 为单页应用提供回退文件

Go 的 http.FileServer 只负责把请求路径映射到文件，它并不知道 React、Vue 或其他单页应用的客户端路由。于是 /assets/app.js 能正常返回，但用户直接刷新 /users/42 时，服务器会查找同名文件并得到 404。解决办法是在 FileServer 外面加一层 Handler：真实文件按原路径提供，缺失且面向 HTML 的无扩展名路径才回退到入口页。

官方文档：https://pkg.go.dev/net/http#FileServer

FileServer 为什么不会自动回退

http.FileServer 的职责很明确：它从 http.FileSystem 打开与 URL 路径对应的文件并写入响应。Go 官方还特别说明，请求路径如果以 /index.html 结尾，FileServer 会把它重定向到去掉 index.html 的路径。这是静态站点的规范化行为，却不是 SPA 的“所有前端路由都返回入口页”。

因此，直接把构建目录交给 FileServer 只能解决资源托管：

// dist 目录包含 index.html 和 assets 等前端构建产物。
static := http.FileServer(http.Dir("./dist"))

// 根路径交给静态文件服务，但缺失的客户端路由仍然会得到 404。
http.Handle("/", static)

问题不在 FileServer “配置错了”，而在服务端还缺少一条清晰的回退策略。最危险的修补是把任何打开失败都改成 index.html：浏览器请求一个不存在的 JavaScript 文件时也会收到 200 和 HTML，最终只留下难懂的 MIME 类型或语法错误。

先判断真实文件，再决定是否回退

一个稳妥的边界是：存在的文件和目录继续交给 FileServer；不存在的路径只有同时满足“无扩展名”和“客户端接受 HTML”时，才视为前端导航。这样 /settings/profile 可以进入 SPA，而 /assets/missing.js 仍保留真正的 404。

下面的 Handler 只依赖标准库，并且可以接收磁盘文件系统、embed.FS 的子树或其他 fs.FS：

package main

import (
    "errors"
    "io/fs"
    "net/http"
    "path"
    "strings"
)

type spaHandler struct {
    root  fs.FS
    files http.Handler
}

func newSPAHandler(root fs.FS) http.Handler {
    return spaHandler{
        root: root,
        // http.FS 把 io/fs.FS 适配为 http.FileSystem。
        files: http.FileServer(http.FS(root)),
    }
}

func (h spaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet && r.Method != http.MethodHead {
        // 静态站点只接受读取方法，其他方法明确拒绝。
        w.Header().Set("Allow", "GET, HEAD")
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }

    // io/fs 使用不带前导斜杠、以正斜杠分隔的名称。
    name := strings.TrimPrefix(path.Clean("/"+r.URL.Path), "/")
    if name == "." || name == "" {
        // 根请求直接让 FileServer 查找 index.html。
        h.files.ServeHTTP(w, r)
        return
    }

    if _, err := fs.Stat(h.root, name); err == nil {
        // 文件或目录真实存在，保留 FileServer 的缓存、范围请求和重定向行为。
        h.files.ServeHTTP(w, r)
        return
    } else if !errors.Is(err, fs.ErrNotExist) {
        // 权限或底层 I/O 错误不能伪装成前端路由。
        h.files.ServeHTTP(w, r)
        return
    }

    if path.Ext(name) != "" || !acceptsHTML(r) {
        // 缺失的带扩展名资源或非 HTML 请求保持普通 404。
        h.files.ServeHTTP(w, r)
        return
    }

    clone := r.Clone(r.Context())
    clonedURL := *r.URL
    // 改成根路径，让 FileServer 提供根目录的 index.html。
    // 不直接写 /index.html，避免触发 FileServer 的规范化重定向。
    clonedURL.Path = "/"
    clonedURL.RawPath = ""
    clone.URL = &clonedURL
    h.files.ServeHTTP(w, clone)
}

func acceptsHTML(r *http.Request) bool {
    accept := r.Header.Get("Accept")
    // 空 Accept 兼容直接输入地址和部分简单客户端。
    return accept == "" || strings.Contains(accept, "text/html")
}

这里没有先写响应头，因此判断失败后仍能完整地把请求交给 FileServer。查询字符串也会保留，因为只复制并修改了 URL 的 Path。如果应用允许带点号的前端路由，例如 /release/v1.2，就不能机械依赖 path.Ext，应改成只把约定的资源前缀（如 /assets/）排除在回退之外。

用根路径而不是 /index.html 提供入口页

回退时把路径改成 / 是一个容易忽略的小细节。FileServer 对以 /index.html 结尾的请求有特殊重定向规则；如果内部回退路径直接写成 /index.html，处理器可能返回重定向，而不是立即提供入口文件。把克隆请求的路径改成根目录，FileServer 会按目录索引规则打开 index.html，同时用户地址栏仍保留原来的客户端路由。

把 API、资源缺失和前端路由分开

SPA Handler 不应该成为整个服务的万能兜底。使用 http.ServeMux 时，把 API 注册在更具体的模式上，再把 / 留给前端。这样 API 的 404、认证失败或方法错误不会被入口页覆盖。

mux := http.NewServeMux()

// 更具体的 API 路由优先匹配，不让接口错误落到 SPA 入口页。
mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
    http.Error(w, "API route not found", http.StatusNotFound)
})

// 根路由最后承接静态文件和前端导航。
mux.Handle("/", newSPAHandler(dist))

server := &http.Server{
    Addr:    ":8080",
    Handler: mux,
}

// ListenAndServe 的正常关闭也会返回 http.ErrServerClosed，生产环境可单独判断。
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
    log.Fatal(err)
}

如果 API 与前端不在同一进程，也建议在反向代理或网关层保持相同边界：只为页面导航配置入口页回退，不要把资源、接口和监控端点全部改写成 200 HTML。

嵌入构建产物的完整写法

embed.FS 实现了 fs.FS，其中普通文件还实现了 FileServer 所需的 io.Seeker。通过 fs.Sub 把 web/dist 变成文件系统根目录，就不必在 URL 中暴露构建目录前缀。

package main

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

//go:embed web/dist
var web embed.FS

func main() {
    // 把嵌入树的 web/dist 子目录变成静态站点根目录。
    dist, err := fs.Sub(web, "web/dist")
    if err != nil {
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    // API 先注册到更具体的路径，避免被页面回退覆盖。
    mux.HandleFunc("/api/health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"ok":true}`))
    })
    mux.Handle("/", newSPAHandler(dist))

    // 服务退出时保留真实错误，便于运维系统发现故障。
    if err := http.ListenAndServe(":8080", mux); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}

//go:embed 的模式相对当前 Go 包目录解释，路径分隔符始终是正斜杠。构建前要确保 web/dist 至少有一个匹配文件，否则无效模式会让 Go 构建失败。磁盘部署时只需把 dist 换成 os.DirFS("./dist")，SPA Handler 本身无需改变。

常见问题

为什么不能让所有 404 都返回 index.html？

因为缺失的脚本、样式、字体和图片也会变成 200 HTML，浏览器随后会报告 MIME 类型或解析错误。资源错误应该保留 404，前端路由才回退。

为什么先调用 fs.Stat，不直接 Open？

fs.Stat 清楚表达“判断真实目标是否存在”的意图；底层没有实现 StatFS 时，标准库会退回到 Open、Stat 和 Close。它会多做一次文件访问，若静态请求量很大，可以用自定义 http.FileSystem 或缓存存在性结果优化，但不要牺牲错误边界。

Go 1.22 以后能否使用 http.FileServerFS？

可以。http.FileServerFS 直接接受 fs.FS，但回退策略仍要由外层 Handler 实现。若项目需要兼容更早的 Go 版本，http.FileServer(http.FS(root)) 更通用。

前端路由包含点号怎么办？

把“无扩展名”规则替换为“资源前缀白名单”更合适，例如仅让 /assets/、/favicon.ico 和其他固定资源路径保持 404，其余 HTML 导航允许回退。