Nginx默认仅在200响应中发送ETag，304/4xx/5xx响应中会自动过滤ETag头；需用add_header ... always;强制透传或注入，否则客户端条件请求可能异常。
默认情况下，Nginx 只在响应状态码为 200（OK）时生成并发送 ETag 头；对于 304 Not Modified、404 Not Found、500 Internal Server Error 等非 200 响应，即使原始资源有 ETag，Nginx 也不会透传或重写该头——这会导致某些客户端（如前端缓存代理、CDN 或测试工具）对条件请求（If-None-Match）行为异常，尤其在调试或灰度场景中容易误判缓存有效性。
理解 Nginx 的 ETag 行为边界
Nginx 自身不主动计算 ETag，而是依赖上游（如后端应用）提供，或由 etag on 指令配合静态文件的 last_modified 和文件大小自动生成。但无论来源如何，Nginx 的内置逻辑会过滤掉所有非 200 响应中的 ETag 头，且该行为不可通过常规配置关闭。
-
etag on;仅影响 200 响应的生成，对 304/4xx/5xx 无作用 -
add_header ETag ...;在非 200 响应中默认被忽略（除非显式启用always） -
proxy_pass后端返回的 ETag，在非 200 时会被 Nginx 主动剥离
强制在非 200 响应中保留或注入 ETag
使用 add_header ... always; 是唯一可靠方式，它绕过 Nginx 的状态码过滤逻辑，确保头字段出现在任意响应中：
location /api/ {
proxy_pass http://backend;
# 强制透传后端返回的 ETag（含 4xx/5xx）
proxy_hide_header ETag; # 先清除可能被过滤的旧 ETag
add_header ETag $upstream_http_etag always;
<pre class="brush:php;toolbar:false;"># 或者手动构造（适用于需统一标识的场景）
# add_header ETag "W/\"static-v1\"" always;
}
注意：$upstream_http_etag 是 Nginx 预定义变量，表示上游响应中的 ETag 值；若后端未返回，该变量为空，此时可配合 map 或 Lua 做 fallback。
针对 304 响应的特殊处理
标准 HTTP 要求 304 响应不能包含消息体，但可包含部分头字段（如 ETag、Cache-Control）。Nginx 默认不发 ETag 给 304，但你可以安全补充：
- 304 是 Nginx 自行生成的（如匹配了
If-None-Match），此时用add_header ETag ... always;即可 - 若 304 由后端返回，需确保后端自己设置了 ETag，并用
add_header ETag $upstream_http_etag always;透传 - 避免在 304 中设置与原始 200 不一致的 ETag，否则破坏语义一致性
验证与调试建议
用 curl -v 或 Postman 检查各类状态码下的实际响应头：
# 触发 304 curl -H "If-None-Match: \"abc\"" -I http://example.com/file.js <h1>触发 404 并检查是否含 ETag</h1><p>curl -I <a href="https://www.php.cn/link/d7aa1c786d6e945204d4278cc64b5b35">https://www.php.cn/link/d7aa1c786d6e945204d4278cc64b5b35</a></p>
在 Nginx 日志中开启 log_format 记录 $upstream_http_etag 和 $status，便于排查透传是否生效：
log_format etag_debug '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_if_none_match" "$upstream_http_etag"';
不复杂但容易忽略：Nginx 对 ETag 的状态码限制是硬编码逻辑，没有开关，必须用 always 显式覆盖。
