net/http ServeFile 处理条件请求与缓存头

用 net/http.ServeFile 返回静态文件时，文件的修改时间可以直接参与条件请求：标准库会根据文件信息写入 Last-Modified，并在请求带有匹配的 If-Modified-Since 时返回 304 Not Modified，避免重复传输文件内容。真正容易混淆的是，ETag 和 Cache-Control 不是“调用 ServeFile 就自动生成”的业务缓存策略，需要在调用前明确设置。

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

这篇文章按一次静态资源上线时的决策顺序拆开边界：先让标准库负责文件条件判断，再由应用补上缓存时长和版本标识，最后检查路径和失效策略。

结论：稳定文件可以直接依赖 ServeFile 的修改时间完成协商缓存；需要强缓存或发布即失效时，再由业务方设置 Cache-Control 和 ETag。

ServeFile 自动处理什么，缓存策略还缺什么

ServeFile 最终会读取文件信息，并把文件的修改时间交给静态内容处理逻辑。只要修改时间不是零值或 Unix 起点，响应就可以带上 Last-Modified。客户端下一次把这个时间放入 If-Modified-Since，且文件没有更新时，服务端可以只返回 304。

这是一种基于时间的协商缓存，不等于“浏览器永远不请求”。如果希望浏览器在一段时间内直接复用本地副本，需要显式写入 Cache-Control；如果希望内容由稳定版本标识判断，则要在响应中预先设置符合 RFC 7232 的 ETag，ServeContent 的条件判断才会使用它。

先固定文件边界，再让条件请求生效

ServeFile 的 name 参数决定真正读取的文件，普通情况下不会用 r.URL.Path 再替换它。问题在于很多处理器会直接把用户路径拼进文件名，这会把路径清洗责任推给业务代码。官方实现会拒绝请求 URL 中的 .. 路径段，但应用仍应在进入 ServeFile 前把 URL 映射到受控目录和白名单文件。

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "net/http"
)

func assetHandler(w http.ResponseWriter, r *http.Request) {
    // 只允许固定资源名，避免把未清洗的 URL 路径拼到文件系统路径中。
    if r.URL.Path != "/assets/app.js" {
        http.NotFound(w, r)
        return
    }

    // ETag 必须在 ServeFile 处理条件请求前写入响应头。
    version := sha256.Sum256([]byte("app-js-build-20261011"))
    w.Header().Set("ETag", `"`+hex.EncodeToString(version[:8])+`"`)
    // 版本化资源可以允许短时间强缓存；发布策略变化时应同步更新版本标识。
    w.Header().Set("Cache-Control", "public, max-age=300")

    // 文件修改时间仍由 ServeFile 读取，用于 Last-Modified 协商。
    http.ServeFile(w, r, "./public/assets/app.js")
}

这里的哈希只是示例版本标识，生产环境通常直接把构建版本或内容摘要写入发布清单。关键顺序是先写 ETag，再调用 ServeFile；若条件匹配，底层处理逻辑可以据此返回 304 或继续输出文件。

304、ETag 与 Cache-Control 的取舍

可以把三个响应头理解成三种不同职责：

如果同时提供 ETag 和 Last-Modified，条件判断会优先处理请求中的 ETag 条件；没有匹配的 ETag 条件时，才可能继续用修改时间判断。对于不可变的带版本文件，可以使用较长的 max-age 并在文件名中带构建版本；对于固定 URL 的业务配置，则应缩短缓存时间或要求重新验证，避免旧内容长期留在 CDN。

上线前的四个边界检查

• 路径：不要把原始 URL 路径直接传给 filepath.Join 后再调用 ServeFile；先把资源名映射到固定目录。
• 重定向：请求路径以 /index.html 结尾时，ServeFile 有特殊的规范化重定向；若不需要该行为，应调整路径或使用 ServeContent。
• 错误响应：文件读取或 Range 处理出错时，标准库默认会清理 Cache-Control、ETag、Last-Modified 等缓存头，避免错误页面继承成功响应的缓存语义。
• 失效：只改 Cache-Control 不能让已经带长 max-age 的旧资源立刻更新；固定 URL 的资源需要重新验证，版本化 URL 则要让版本标识随发布变化。

实际排查时，先看文件修改时间是否可靠，再看响应中是否真的写入 ETag 和 Cache-Control，最后确认代理层没有覆盖或延长缓存策略。这样可以把“没有返回新文件”拆成条件命中、缓存复用和资源路径三个独立问题。

相关问题

ServeFile 会自动生成 ETag 吗？不会。只有调用方预先设置响应头中的 ETag，ServeContent 的条件判断才会使用它。

为什么请求返回 304 但响应体为空？304 的目的就是告诉客户端继续使用已有表示，正常情况下不应携带完整文件内容。

固定 URL 的配置文件适合长时间缓存吗？通常不适合。应缩短 max-age 或要求重新验证；如果能改成版本化 URL，缓存失效会更容易管理。