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

在 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，可能需额外配置

验证头部是否生效

可通过后端日志或临时调试接口确认头部是否到达：

• 在后端打印所有请求头（如 Express 中 console.log(req.headers)）
• 用 curl -H "X-Custom-Id: abc123" http://your-nginx-domain/api/test 发起测试请求
• 检查 Nginx 错误日志（error_log）是否有 header 相关警告（如非法字符、过大等）