Nginx add_header 指令实例分析

add_header 是 Nginx 中用于向 HTTP 响应添加自定义头部的指令，它在安全配置、缓存控制、跨域设置等方面非常有用。下面我将详细分析这个指令的使用方法和实际应用场景。

基本语法

add_header name value [always];

• name: 头部字段名
• value: 头部字段值
• always: 可选参数，表示无论响应代码是什么都添加该头部（默认只在 200, 201, 204, 206, 301, 302, 303, 304, 307, 308 时添加）

常见应用实例

1. 安全相关头部

add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header X-XSS-Protection "1; mode=block";
add_header Referrer-Policy "no-referrer-when-downgrade";
add_header Content-Security-Policy "default-src 'self'";

2. 缓存控制

# 禁止缓存
add_header Cache-Control "no-store, no-cache, must-revalidate";

# 长期缓存静态资源
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 365d;
    add_header Cache-Control "public, immutable";
}

3. CORS 跨域设置

location /api/ {
    add_header 'Access-Control-Allow-Origin' '$http_origin';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';

    # 处理预检请求
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Max-Age' 1728000;
        add_header 'Content-Type' 'text/plain; charset=utf-8';
        add_header 'Content-Length' 0;
        return 204;
    }
}

4. 自定义应用头部

add_header X-Powered-By "MyApp/1.0";
add_header X-Request-ID $request_id;

5. 使用 always 参数

# 即使返回错误状态码也添加安全头部
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;

注意事项

1. 继承规则：add_header 指令不会从上层配置继承，如果在某个作用域内使用了 add_header，会覆盖上层的同名头部设置。

2. 重复头部：如果需要添加多个相同名称的头部，可以使用 add_header 多次，或者使用变量构造值。

3. 性能影响：过多的自定义头部会增加网络传输的开销，应合理使用。

4. 变量支持：add_header 支持使用 Nginx 变量，如 $host, $server_name 等。

调试技巧

可以使用 curl -I 命令检查头部是否按预期添加：

curl -I https://example.com

或者更详细地查看所有响应头：

curl -v https://example.com

常见问题解决

问题1：为什么我的 add_header 不生效？ - 检查是否在正确的配置块中（server/location） - 检查是否有更高优先级的配置覆盖了你的设置 - 尝试添加 always 参数

问题2：如何删除不需要的头部？ - 使用 proxy_hide_header 或 fastcgi_hide_header 来隐藏上游服务器返回的特定头部 - 对于某些内置头部，可能需要重新编译 Nginx 才能完全移除

通过合理使用 add_header 指令，可以显著增强 Web 应用的安全性、可维护性和功能性。