如何通过Nginx开启Etag提升高频访问API的响应速度指南-Nginx-PHP中文网

启用 nginx 的 etag on 指令可基于 last-modified 和文件大小自动生成弱 etag，需后端返回 last-modified 头，配合 cache-control: public, max-age=0, must-revalidate，并通过 304 响应实现协商缓存。

如何通过nginx开启etag提升高频访问api的响应速度指南

开启 ETag 能让客户端（如浏览器、App）对未修改的 API 响应直接复用本地缓存，跳过服务端处理和网络传输，显著降低延迟和服务器压力。Nginx 本身不生成 ETag，但可通过 add_header 或配合后端（如 FastAPI、Node.js）协同实现；更常用且推荐的方式是启用 Nginx 的内置 etag on 指令——它会基于文件最后修改时间（Last-Modified）和大小自动生成弱校验 ETag，适用于静态资源和代理返回的、带 Last-Modified 响应头的 API。

确认 API 响应已携带 Last-Modified 或 ETag

Nginx 的 etag on 只对响应中含 Last-Modified 头的请求生效（自动派生 ETag），若后端 API 未返回该头，Nginx 不会添加 ETag。因此第一步是检查真实响应：

用 curl -I https://api.example.com/v1/data 查看响应头，确认存在 Last-Modified（推荐）或已有 ETag
若无 Last-Modified，需在后端添加：例如 Express 中加 res.set('Last-Modified', new Date().toUTCString())；FastAPI 可用 Response(headers={"Last-Modified": ...})
避免手动设置 ETag 后又开启 etag on，可能引发冲突；二者选其一即可

在 Nginx 配置中启用 ETag 自动生成

在对应 server 或 location 块中启用即可，无需额外模块：

添加 etag on; —— 这是关键指令，Nginx 默认为 off
确保未设置 expires 或 add_header Cache-Control 覆盖了协商缓存逻辑；建议搭配 Cache-Control: public, max-age=0, must-revalidate，明确启用条件 GET

示例片段：

location /v1/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    etag on;
    add_header Cache-Control "public, max-age=0, must-revalidate";
}

验证 ETag 是否生效及客户端行为

生效后，客户端第二次请求会自动带上 If-None-Match（对应 ETag）或 If-Modified-Since（对应 Last-Modified）：

用 curl 测试：第一次请求返回 200 OK + ETag: "abc123"；第二次加头 curl -H "If-None-Match: \"abc123\"" https://...，应返回 304 Not Modified
Chrome DevTools → Network → 点击请求 → Headers → 查看 Request Headers 是否含 If-None-Match，Response Headers 是否返回 304
注意：若后端返回了 Cache-Control: no-store 或 max-age=0 但没配 must-revalidate，部分客户端可能跳过协商缓存

高频 API 场景下的补充建议

纯 JSON 接口不像静态文件有天然修改时间，需更谨慎设计缓存策略：

对内容稳定、更新频率低的接口（如配置项、字典表），可由后端在数据变更时主动更新 Last-Modified 时间戳，或计算内容哈希作为强 ETag（如 ETag: "W/\"sha256-hash\""）
Nginx 层不建议用 add_header ETag 手动注入，因无法感知后端响应变化，易导致缓存不一致
若使用 Nginx 缓存（proxy_cache），ETag 会自动与缓存条目联动；但需确保 proxy_cache_valid 包含 304 状态码，例如：proxy_cache_valid 200 302 304 10m;

不复杂但容易忽略：ETag 不是“开个开关就提速”，它依赖客户端发起条件请求 + 服务端正确响应 304。只要后端提供 Last-Modified、Nginx 开启 etag on、客户端支持协商缓存，高频读接口的重复请求就能秒级返回，服务器 CPU 和带宽压力同步下降。