Nginx之proxy_set_header参数总结

目录

[1. proxy_set_header 的基本语法](#1. proxy_set_header 的基本语法)

[2. 核心参数解析](#2. 核心参数解析)

[2.1 设置Host 头](#2.1 设置Host 头)

[2.2 客户端真实 IP 传递](#2.2 客户端真实 IP 传递)

[2.2.1 X-Real-IP​​](#2.2.1 X-Real-IP)

[2.2.2 X-Forwarded-For​​](#2.2.2 X-Forwarded-For)

[2. 3 协议与安全头](#2. 3 协议与安全头)

[2.3.1 X-Forwarded-Proto​​](#2.3.1 X-Forwarded-Proto)

[2.3.2 安全头​​](#2.3.2 安全头)

[2.4 禁用或修改特定请求头](#2.4 禁用或修改特定请求头)

[2.4.1 禁用请求头:将值设为空字符串。](#2.4.1 禁用请求头:将值设为空字符串。)

[2.4.2 修改请求头:设置新的值。](#2.4.2 修改请求头:设置新的值。)

[2.5 支持 CORS(跨域资源共享)](#2.5 支持 CORS(跨域资源共享))

[​​2.6 连接控制​](#2.6 连接控制)

[2.6.1 支持 HTTP/1.1 持久连接](#2.6.1 支持 HTTP/1.1 持久连接)

[2.6.2 避免 Connection 头冲突](#2.6.2 避免 Connection 头冲突)

[2.6.3 WebSocket 协议升级](#2.6.3 WebSocket 协议升级)

[2.7 自定义头传递​](#2.7 自定义头传递)

[2.8 缓存控制​](#2.8 缓存控制)

[2.9 请求头删除](#2.9 请求头删除)

[3 注意事项](#3 注意事项)

[3.1 下划线](#3.1 下划线)

[​​​​​​3.2 指令位置](#3.2 指令位置)

[3.3 空值处理](#3.3 空值处理)


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 必须放在 locationserver 块中,否则无效。

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;
    }
}