Nginx 中怎么配置 proxy_set_header 转发自定义头部信息-Nginx-PHP中文网

proxy_set_header用于设置转发给后端的http请求头，必须在含proxy_pass的location或server块中配置；它不透传未显式声明的头，可覆盖默认值（如host）、传递真实ip（x-real-ip）、追加代理链（x-forwarded-for）、注入自定义头（如x-app-version），并需注意变量用法、下划线支持及生效范围。

nginx 中怎么配置 proxy_set_header 转发自定义头部信息

在 Nginx 中使用 proxy_set_header 可以将自定义请求头（或修改默认头）转发给后端服务，这是反向代理场景中传递客户端信息、认证凭证或业务标识的常用方式。

基本语法和作用

proxy_set_header 用于设置发送给后端服务器的 HTTP 请求头。它必须写在 location 或 server 块中，且仅对 proxy_pass 生效。Nginx 默认会清除部分原始请求头（如 Host），所以需要显式设置才能透传。

未显式设置的头部，Nginx 不会自动转发
已设置的头部会覆盖默认值（例如 Host 默认被设为 $proxy_host，可改为 $http_host 保持原样）
变量如 $http_x_forwarded_for、$remote_addr 等可用于动态构造头部值

常见自定义头部配置示例

以下是在 location 块中常用的 proxy_set_header 配置：

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

透传原始 Host 头：proxy_set_header Host $http_host;（避免后端看到的是 upstream 地址）
添加客户端真实 IP：proxy_set_header X-Real-IP $remote_addr;
追加 X-Forwarded-For 链路：proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;（自动拼接，比直接用 $remote_addr 更安全）
传递自定义业务头：proxy_set_header X-App-Version "v2.3.1";
转发 Authorization（如 Bearer Token）：proxy_set_header Authorization $http_authorization;（注意：需确保客户端确实带了该头，且 Nginx 未因安全策略屏蔽）

注意事项和易错点

配置时容易忽略的关键细节：

proxy_set_header 在 http 块中全局设置时，会被 server 或 location 中同名指令覆盖，建议按需就近定义
若要清空某个头部（不发给后端），不能写成 proxy_set_header X-Some-Header "";，而应使用 proxy_hide_header X-Some-Header;（但该指令只影响响应头）；如需彻底不发送请求头，只能不在配置中声明
某些头部名含下划线（如 X-API_Key）默认被 Nginx 忽略，需开启 underscores_in_headers on;（放在 server 或 http 块）
如果后端是 Node.js/Express 等框架，注意它们默认不解析带下划线的 header，可能需额外配置