首页 > 网站技巧 > 服务器 > nginx > nginx proxy_set_header参数

Nginx中的proxy_set_header核心参数解析

2025-08-25 16:24:07 作者：岚叔运维

文章详解Nginx中proxy_set_header指令的语法与用途,涵盖设置Host头、传递真实IP、协议信息、连接控制、CORS支持、自定义头及缓存管理,强调需注意指令位置、空值处理和特殊头格式,感兴趣的朋友跟随小编一起看看吧

1. proxy_set_header的基本语法

proxy_set_header  <HeaderName>   <HeaderValue>;

• HeaderName：需设置的请求头名称（如 Host、X-Real-IP）。

• HeaderValue：请求头的值，可以是静态字符串、Nginx 内置变量（如 $host、$remote_addr）或两者的组合

2. 核心参数解析

2.1 设置Host 头

作用：指定后端服务器的主机名。确保后端服务器接收到的 Host 头与客户端请求一致，避免因 Host 不匹配导致的 400/404 错误。若未设置，默认传递代理服务器的主机名。
配置示例：

  proxy_set_header Host $host;          # 传递客户端请求的原始 Host
  proxy_set_header Host $http_host;     # 优先使用请求头中的 Host（若存在）
  proxy_set_header Host backend.example.com;    # 强制指定固定值

场景：当后端应用依赖 Host 头进行路由或生成绝对 URL 时需配置。
示例对比：

1）未设置 proxy_set_header Host

GET / HTTP/1.1
Host: backend.example.com  # 默认由 proxy_pass 决定

2）设置 proxy_set_header Host $host：

GET / HTTP/1.1
Host: nginx.example.com    # 与客户端请求的 Host 一致

2.2 客户端真实 IP 传递

2.2.1 X-Real-IP

proxy_set_header X-Real-IP $remote_addr;

作用：将客户端真实 IP 写入 X-Real-IP 头，供后端服务器读取。

2.2.2 X-Forwarded-For

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

作用：在原有 X-Forwarded-For 头的基础上追加客户端 IP（支持多级代理）

2.3 协议与安全头

2.3.1 X-Forwarded-Proto

proxy_set_header X-Forwarded-Proto $scheme;

作用：传递原始请求协议（HTTP/HTTPS），用于后端生成正确链接。

2.3.2 安全头

proxy_set_header X-Frame-Options "SAMEORIGIN";  # 防点击劫持
proxy_set_header X-XSS-Protection "1; mode=block";  # 防 XSS 攻击

2.4禁用或修改特定请求头

2.4.1 禁用请求头：将值设为空字符串

proxy_set_header User-Agent "";  # 禁用 User-Agent 头

2.4.2 修改请求头：设置新的值

proxy_set_header Authorization "Bearer <token>";  # 修改授权头

2.5 支持 CORS（跨域资源共享）

proxy_set_header Origin $http_origin;   # 直接传递客户端Origin值‌

作用：保留客户端原始 Origin 头（适用于动态域名场景）

2.6 连接控制

proxy_set_header Connection "";

2.6.1 支持 HTTP/1.1 持久连接

问题：默认情况下，Nginx 的 Connection: close 会强制关闭与后端的连接，导致每次请求都需要重新建立 TCP 连接，增加延迟。

解决方案：如果后端服务器支持 HTTP/1.1 的持久连接（Keep-Alive），可以通过以下配置启用：

proxy_set_header Connection "";
proxy_http_version 1.1;

2.6.2 避免 Connection 头冲突

问题：如果客户端请求中包含 Connection: keep-alive，而 Nginx 默认覆盖为 Connection: close，可能导致后端服务器行为异常。

解决方案：通过清空 Connection 头，保留客户端原始意图：

proxy_set_header Connection "";

2.6.3 WebSocket 协议升级

WebSocket 特殊需求：WebSocket 需要协议升级（Upgrade: websocket），此时必须设置 Connection: upgrade：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

注意：此时不能清空 Connection 头，否则握手失败。

2.7自定义头传递

proxy_set_header X-Custom-Header "DynamicValue";

作用：传递业务标识、灰度发布标记等自定义信。

2.8缓存控制

proxy_set_header Cache-Control "no-cache, no-store";

作用：强制后端禁用缓存，适用于动态内容。

2.9 请求头删除

proxy_set_header Accept-Encoding "";  # 禁用后端压缩

优点：
避免后端服务器进行压缩处理，减少 CPU 开销。
缺点：
响应内容未压缩，可能导致传输数据量增加，影响网络性能（尤其对大文件或高并发场景）。

3 注意事项

3.1 下划线

若自定义头含下划线（如 X-My_Header），需在配置中开启：

underscores_in_headers on;

3.2指令位置

proxy_set_header 必须放在 location 或 server 块中，否则无效。

3.3 空值处理

设置 proxy_set_header field ""; 会从请求中移除该头。
若值包含变量且变量为空，头字段会被移除，这样就能阻止它们被传递。

下面是一个完整的配置示例，它会禁用所有默认头，仅传递必要的客户端信息：

server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://backend;
        # 禁用默认传递的头
        proxy_set_header Host "";
        proxy_set_header Connection "";
        proxy_set_header User-Agent "";
        proxy_set_header Accept "";
        proxy_set_header Accept-Encoding "";
        # 仅传递必要的头
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # 若需要授权头
        proxy_set_header Authorization $http_authorization;
    }
}

到此这篇关于Nginx之proxy_set_header核心参数解析的文章就介绍到这了,更多相关nginx proxy_set_header参数内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！