Go http.ServeContent 出错时怎么排查条件请求

用 Go 的 http.ServeContent 返回文件时，条件请求异常通常不是“缓存失效”这么简单。先检查四个输入：content 是否能 Seek、modtime 是否有效、ETag 是否稳定、请求里的 If-* 与 Range 是否被中间层改写。它们分别决定长度、缓存命中和分段响应。

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

先把 ServeContent 的四个输入边界对齐

这个函数的签名已经暴露了排查顺序：name 主要影响 MIME 类型推断；modtime 影响 Last-Modified；content 必须是可定位的 io.ReadSeeker。如果把数据库流、网络流或只能顺序读取的 reader 直接传入，函数无法可靠知道总长度，后续条件请求和 Range 都会变得不可预测。

用稳定的 ETag 和 modtime 交给标准库判断

不要在 handler 外层先手写一套 “If-None-Match 等于就返回 304” 的逻辑，再调用 ServeContent。这样容易漏掉优先级和 Range 组合。更稳妥的做法是在调用前准备好资源版本的 ETag 与修改时间，把条件判断交给标准库：

func asset(w http.ResponseWriter, r *http.Request) {
	// 文件版本号必须稳定；内容变更时才生成新的 ETag。
	const etag = "\"asset-v3\""
	path := "./public/manual.pdf"

	f, err := os.Open(path)
	if err != nil {
		// 资源不存在时直接结束，避免把错误文件传给 ServeContent。
		http.NotFound(w, r)
		return
	}
	defer f.Close() // 无论条件命中与否，都释放文件描述符。

	info, err := f.Stat()
	if err != nil {
		http.Error(w, "读取资源信息失败", http.StatusInternalServerError)
		return
	}
	w.Header().Set("ETag", etag)
	http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

这里的关键不是把 ETag 写成固定字符串，而是让它代表内容版本。资源替换后仍沿用旧 ETag，会让客户端错误地拿到 304；每次请求都随机生成 ETag，则失去缓存复用。modtime 也应来自同一个资源版本，不能一会儿取文件时间、一会儿取数据库时间。

用四类请求把 304、206 和 416 分开看

排错不要只刷新浏览器。用同一个 URL 发几类请求，可以快速确认是哪一条条件链出了问题：

# 先观察完整响应头，确认 ETag 和 Last-Modified 是否存在。
curl -i http://localhost:8080/manual.pdf

# 将上一响应的时间带回去；资源未变时通常应得到 304。
curl -i -H 'If-Modified-Since: Wed, 01 Jan 2030 00:00:00 GMT' \
  http://localhost:8080/manual.pdf

# 使用稳定 ETag 检查实体标签命中。
curl -i -H 'If-None-Match: "asset-v3"' \
  http://localhost:8080/manual.pdf

# 合法范围应带 206 和 Content-Range；故意越界时关注 416。
curl -i -H 'Range: bytes=0-99' http://localhost:8080/manual.pdf

预期关系可以记成：普通 GET 返回 200，条件命中返回 304，合法 Range 返回 206，无法满足的范围返回 416。If-Range 还会把 ETag 或日期作为“是否允许继续分段”的条件；因此看到 200 不一定是函数坏了，也可能是校验条件不匹配而回退到整段内容。

如果 If-Modified-Since 没有作用，先看 Last-Modified 是否真的发送，以及传入的 modtime 是否为零值或 Unix epoch。如果 ETag 条件没作用，确认 ETag 是在调用前写入的，并检查反向代理是否删除或改写了它。

遇到出错响应时，按证据定位而不是盲改缓存

出现 500，优先检查 Seek 是否支持从当前位置跳到末尾，以及内容读取后能否回到正确位置。出现 416，检查客户端的 Range 是否超过当前长度、是否由代理拼接成了非法区间。官方文档还说明，处理错误时默认可能移除 Cache-Control、Content-Encoding、ETag 和 Last-Modified；所以不能仅凭错误响应里没有 ETag，就断定调用前没有设置。

记录下面这组最小信息，通常一次请求就能缩小范围：

• 请求方法、URL、If-None-Match、If-Modified-Since、If-Range 与 Range；
• 响应状态、Content-Length、Content-Range、ETag、Last-Modified；
• 资源版本、文件大小、modtime，以及代理前后是否发生 header 改写。

确认了边界后再修复：让资源实现真正的 io.ReadSeeker，统一版本来源，或修正代理的缓存头策略。不要因为某次返回 200 就立即关闭缓存，也不要把 304 当成业务接口失败；它只是告诉客户端继续使用已有副本。

常见问题

modtime 为零值时为什么没有 304？

因为 ServeContent 只有在修改时间有效时才据此生成 Last-Modified 并处理 If-Modified-Since。需要条件缓存时，应传入真实且稳定的资源更新时间，同时配置 ETag。

ETag 应该放在调用前还是调用后？

放在调用 ServeContent 前。标准库需要读取这个响应头来处理 If-Match、If-None-Match 和 If-Range。

为什么 Range 请求返回 200 而不是 206？

可能是 Range 不合法、If-Range 校验未命中而回退整段响应，也可能是代理移除了 Range。先对照 Content-Range 和 ETag，再检查中间层。

内存缓冲区能不能传给 ServeContent？

可以，只要包装成支持 Seek 的 reader，例如 bytes.Reader；关键是长度定位和回到内容起点都必须可靠。