如何利用 map 变量实现针对特定后缀文件动态追加 Vary: Accept-Encoding 头部-Nginx-PHP中文网

应使用 nginx 的 map 指令结合 $sent_http_content_type 动态添加 vary: accept-encoding 头部，仅对 text/ 类型及 js/css/html 等文本后缀响应生效，并需加 always 参数以覆盖 304 响应。

如何利用 map 变量实现针对特定后缀文件动态追加 vary: accept-encoding 头部

可以通过 Nginx 的 map 指令结合 add_header，在匹配特定后缀的静态资源响应中动态添加 Vary: Accept-Encoding 头部。关键在于：仅对支持压缩（如 .js、.css、.html）且实际被压缩的响应添加该头，避免误加到图片、字体等二进制文件上。

定义后缀白名单映射

在 http 块中使用 map 将请求 URI 后缀映射为布尔标记（1 表示需加 Vary，0 表示不加）：

map $sent_http_content_type $add_vary_encoding {
    default                          0;
    ~*^text/                           1;
    ~*\.(js|css|html|htm|xml|json)$   1;
}

说明：
• $sent_http_content_type 是响应已确定的 MIME 类型，比 $request_uri 更可靠（避免后缀欺骗）；
• 正则匹配 text/ 开头类型（如 text/css、text/javascript）；
• 补充匹配常见文本类后缀，覆盖未正确设置 MIME 的情况；
• 顺序重要：更具体的规则放后面，会被优先匹配。

条件化添加 Vary 头部

在 server 或 location 块中，仅当映射值为 1 时添加头部：

location ~* \.(js|css|html|htm|xml|json|txt)$ {
    add_header Vary "Accept-Encoding" always;
    # 其他静态文件配置（如 expires、gzip）
}

但更推荐统一用 map 控制，避免重复 location：

if ($add_vary_encoding = 1) {
    add_header Vary "Accept-Encoding" always;
}

⚠️ 注意：
• 必须加 always 参数，否则仅对 2xx/3xx 响应生效，而 304 等响应也需要该头以保证缓存一致性；
• 不建议在 if 中使用 add_header（Nginx 官方不推荐），更稳妥方式是配合 gzip_vary on + 精确 MIME 映射。

配合 gzip_vary 实现自动管理

若已启用 Gzip，直接开启 gzip_vary 即可由 Nginx 自动添加该头，无需手动 map：

gzip on;
gzip_types text/plain text/css text/javascript application/javascript application/json;
gzip_vary on;

此时 Nginx 会在所有被 gzip 压缩的响应中自动添加 Vary: Accept-Encoding。只需确保：
• gzip_types 包含目标后缀对应 MIME 类型；
• 静态文件响应 MIME 正确（可通过 types 模块或 default_type 校验）；
• 无其他模块（如 proxy_pass）覆盖或清除该头。

验证与调试技巧

检查是否生效：

用 curl -I https://example.com/style.css 查看响应头中是否有 Vary: Accept-Encoding；
对比压缩与未压缩响应（如加 -H "Accept-Encoding: identity"）是否都带该头；
在日志中临时记录变量值：log_format debug '$add_vary_encoding $sent_http_content_type'; 辅助排查映射逻辑。

常见问题：
• 图片（.png）被误加：检查 map 是否错误匹配了 $request_uri 而非 $sent_http_content_type；
• 304 响应缺失该头：确认用了 always 参数；
• 头部未出现：检查是否被后续 add_header 覆盖（Nginx 中同名 header 会覆盖，非追加）。