Go http.ServeFileFS 怎样从 fs.FS 提供文件下载

我最近把一段“从磁盘目录提供下载”的 Go 代码迁到嵌入资源时，真正需要改的不是 HTTP 路由，而是文件系统的抽象边界：http.ServeFile 接受操作系统路径，http.ServeFileFS 接受一个 fs.FS 和一个文件系统内部的相对名称。把资源根先用 fs.Sub 收窄，再传入明确的文件名，迁移会更清楚。

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

这篇只讨论从 fs.FS 提供文件或目录，不展开上传、完整静态站点部署和线上压测。

ServeFileFS 解决的是什么迁移问题

ServeFileFS 的签名是 ServeFileFS(w, r, fsys, name)。其中 w 和 r 仍然是 HTTP 响应与请求，变化集中在后两个参数：fsys 是实现了 fs.FS 的文件系统，name 是这个文件系统中的相对路径。

官方文档标明该函数从 Go 1.22.0 起提供，并要求 fsys 提供的文件实现 io.Seeker。这使它适合把 embed.FS、测试文件系统或其他抽象文件源接入同一套 HTTP 文件响应逻辑。

旧代码通常把物理目录拼成操作系统路径；新代码更适合先决定“服务哪个 fs.FS 的哪个根”，再决定“根下的哪个文件”。这两个决定拆开后，部署目录变化不会直接渗透到处理器。

先用 fs.Sub 固定资源根

嵌入目录往往还包含模板、图标和其他文件。直接把整个 embed.FS 传给处理器，调用方就要不断重复资源前缀。fs.Sub 可以把一个子目录视为新的 fs.FS，让后续的 name 从资源根开始写。

package main

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

// staticFiles 把 public 目录编译进程序，运行时不依赖磁盘上的同名目录。
//go:embed public/*
var staticFiles embed.FS

func main() {
    // 先把可暴露的目录收窄，避免处理器到处拼接 public 前缀。
    assets, err := fs.Sub(staticFiles, "public")
    if err != nil {
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    mux.HandleFunc("GET /download/manual.pdf", func(w http.ResponseWriter, r *http.Request) {
        // name 相对于 assets，而不是相对于项目目录或操作系统根目录。
        http.ServeFileFS(w, r, assets, "manual.pdf")
    })

    // 这里只展示路由注册；实际部署仍需按项目需要配置监听和超时。
    log.Fatal(http.ListenAndServe(":8080", mux))
}

这里的关键不是把 embed.FS 当成特殊对象，而是利用它满足 fs.FS 接口。资源根由 fs.Sub 明确成 public 后，manual.pdf 就不再带上层目录前缀。

name 应该写什么，哪些输入不能直接交给它

name 不是 URL，也不是操作系统绝对路径。io/fs 的路径规则要求使用 UTF-8、斜杠分隔的相对路径；通常不应以斜杠开头，也不能用 .、.. 或空路径元素拼出不规范名称。

如果文件名来自用户输入，先把它当作不可信的路径数据处理。官方文档明确要求在调用 ServeFileFS 前清理这类名称；同时，函数会拒绝请求 URL 中包含 .. 路径元素的情况。更稳妥的做法是把可下载文件映射到白名单，而不是让用户输入直接决定资源名称。

func downloadByKey(w http.ResponseWriter, r *http.Request, assets fs.FS) {
    // 用业务键映射到固定文件名，不把 URL 片段直接当作 fs.FS 路径。
    files := map[string]string{
        "manual": "manual.pdf",
        "terms":  "terms.txt",
    }
    name, ok := files[r.URL.Query().Get("file")]
    if !ok {
        // 未命中白名单时立即结束，避免把任意路径交给文件服务函数。
        http.NotFound(w, r)
        return
    }

    // 显式设置下载提示；ServeFileFS 负责读取文件并写入响应。
    w.Header().Set("Content-Disposition", "attachment; filename=\""+name+"\"")
    http.ServeFileFS(w, r, assets, name)
}

这个例子刻意没有把查询参数直接拼到 name 中。需要动态目录时，应先定义允许的目录集合，再对每个集合调用 fs.Sub 或做严格的路径约束。

旧 ServeFile 写法迁移到新写法

旧代码的关注点是操作系统路径：

// 旧写法：root 是操作系统目录，name 也是磁盘路径。
http.ServeFile(w, r, filepath.Join(root, "public", "manual.pdf"))

如果资源已经来自 fs.FS，迁移后关注点改为“文件系统对象 + 内部名称”：

// 新写法：assets 是资源根，name 只写资源根下的相对文件名。
assets, err := fs.Sub(staticFiles, "public")
if err != nil {
    // 子目录不存在时不要继续注册一个看似可用的下载处理器。
    return err
}
http.ServeFileFS(w, r, assets, "manual.pdf")

这不是简单的函数名替换。迁移时要把 filepath.Join 的结果拆成两个值：前缀变成 fs.Sub 的资源根，剩余部分变成 name。如果原代码依赖目录浏览，还要保留目录传递给文件服务函数的意图。

目录、io.Seeker 和 index.html 的三个边界

第一，ServeFileFS 可以服务文件或目录，但文件系统提供的文件需要实现 io.Seeker；只实现最小 fs.File 的自定义文件源，不能默认具备完整的文件响应能力。

第二，传入目录时，响应行为不等同于一个自定义下载列表。是否展示目录、目录中的索引文件如何处理，应以标准库函数的语义为准，不要把它当成任意模板渲染器。

第三，如果请求 URL 的路径以 /index.html 结尾，官方文档说明 ServeFileFS 会重定向到去掉该文件名的路径。若业务不希望出现这个重定向，就需要重新设计路由或改用更底层的 ServeContent 方案。

迁移完成后按这份清单回归

• 项目的最低 Go 版本是否覆盖 ServeFileFS 的使用范围。
• fs.Sub 的根是否只包含允许公开的资源。
• name 是否是 fs.FS 规则下的相对路径，而不是 URL 或绝对路径。
• 用户输入是否先经过白名单映射或严格清理，没有直接参与路径拼接。
• 自定义文件是否满足标准库对 io.Seeker 的要求。
• 目录响应与 index.html 重定向是否符合产品预期。

我的经验是，先固定资源根，再让每个处理器只看资源根下的名称，迁移成本最低。对于静态的嵌入文件，这种写法比在处理器里反复拼磁盘路径更容易复查；对于复杂权限、动态内容或不支持定位读取的文件源，则不应为了使用一个新 API 而强行套用。

相关问题

ServeFileFS 和 ServeFile 最大的区别是什么？

ServeFile 面向操作系统路径，ServeFileFS 面向 fs.FS 与其内部相对名称。迁移时应同时调整资源根和名称，不只是替换函数名。

embed.FS 能直接传给 ServeFileFS 吗？

可以把实现 fs.FS 的 embed.FS 作为文件系统参数使用；如果嵌入目录较深，先用 fs.Sub 收窄通常更容易维护。

能把 URL 参数直接传给 name 吗？

不建议。用户输入应先经过白名单映射或严格路径处理，避免把 URL 语义和 fs.FS 路径语义混在一起。