Nginx location块中proxy_set_header用于定制转发至后端的HTTP请求头,仅作用于该location内的proxy_pass请求,可设置Host、X-Real-IP等关键头,支持覆盖、透传、注入或清除,实现精准请求头控制。

在 Nginx 的 location 块内使用 proxy_set_header,核心作用是**为该 location 下所有转发到后端的请求,定制化设置 HTTP 请求头**。它不改变客户端发来的原始请求头,而是在代理发出前,按需添加、替换或修正要传给上游服务器的头字段。
控制请求头的传递范围
proxy_set_header 在 location 级生效,只影响该 location 内的 proxy_pass 请求。上级(server 或 http 块)的同名配置会被覆盖,且不会继承叠加——后定义的完全替代前一个。这意味着:
- 不同路径可发送不同的 Host:比如
/admin转发到 admin-backend,设proxy_set_header Host admin.example.com;而/api转发到 api-backend,设proxy_set_header Host api.example.com - 未显式设置的 header(如 Host)会回退到 server 块定义值,或 Nginx 默认的
$proxy_host,容易导致后端收不到预期 Host - 若想透传原始 Host,必须写
proxy_set_header Host $host,不能省略
传递关键客户端元信息
后端服务常依赖这些头做日志、限流、权限或调试。location 中精准设置能避免空值或伪造:
-
proxy_set_header X-Real-IP $remote_addr;—— 直接传递发起请求的真实 IP(非代理 IP) -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 追加当前客户端 IP 到已有链中,保留多层代理路径 -
proxy_set_header X-Forwarded-Proto $scheme;—— 让后端知道原始是 HTTP 还是 HTTPS,避免混合内容或重定向错误
注入业务所需自定义头
可在特定路径下动态注入标识性字段,便于后端路由、鉴权或灰度发布:
proxy_set_header X-Service-Name "payment-api";-
proxy_set_header X-Request-ID $request_id;(需配合log_format或map定义变量) -
location /v2/ { proxy_set_header X-API-Version "v2"; }—— 按路径区分 API 版本
清理或屏蔽敏感头
某些 header 不应透传给后端(如内部 Cookie、调试头),可用空值清除:
-
proxy_set_header Cookie "";—— 删除整个 Cookie 头(注意后端是否依赖) -
proxy_set_header Authorization "";—— 移除认证信息,改由 Nginx 统一处理或注入新 token - 同一 location 中重复设置同一 header,后者会覆盖前者,适合“先清再设”逻辑


















