Nginx proxy_set_header 自定义Header配置教程
一、基础概念解析
proxy_set_header 是 Nginx 反向代理模块中的核心指令，用于在转发请求时修改或添加 HTTP 请求头。通过此指令，可以实现以下功能：

隐藏服务器真实信息（如服务器IP）
传递客户端真实信息（如原始IP地址）
自定义传递业务相关参数（如Token、环境标识等）

⚠️ 关键点：该指令仅在 proxy_pass 存在的上下文中生效，需确保配置在 location 或 server 块中。

二、语法与参数说明
proxy_set_header <HeaderName> <Value>;
​

<HeaderName>：HTTP 请求头名称（如 Host、X-Forwarded-For）
<Value>：可为静态值或 Nginx 内置变量（如 $remote_addr）


三、典型应用场景与示例
1. 传递客户端真实IP
location /api {
    proxy_pass http://backend_server;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
​

X-Real-IP：记录客户端原始IP地址
X-Forwarded-For：标准的IP链记录格式（多个代理会追加）


2. 修改Host头
proxy_set_header Host $host;
​
当后端服务需要根据Host头路由时，需将原始Host传递给后端。

3. 自定义业务Header
proxy_set_header X-Custom-Header "Production-Env";
proxy_set_header Authorization "Bearer ${API_TOKEN}";
​

通过环境变量传递敏感信息（需配合 env API_TOKEN; 配置）
传递环境标识用于后端路由决策


四、常见Header分析表



Header名称
作用描述
示例值




X-Real-IP
记录客户端真实IP地址
192.168.1.100


X-Forwarded-For
记录完整的代理链IP（逗号分隔）
192.168.1.100, 10.0.0.1


Host
控制后端接收的Host头值
api.example.com


X-Forwarded-Proto
传递原始请求协议（HTTP/HTTPS）
https


X-Custom-Header
业务自定义参数（如环境标识、认证Token等）
Auth-Token:ABC123




五、配置验证方法

命令行测试：

curl -I -H "Host:example.com" http://localhost/api
​
检查响应头中是否包含预期Header。

浏览器开发者工具：


打开Network面板
查看请求头（Request Headers）中的自定义Header


六、进阶技巧
1. 动态变量组合
proxy_set_header User-Agent "$http_user_agent (Proxy)";
​
将原始User-Agent与代理标识拼接。
2. 移除敏感Header
proxy_set_header X-Private-Header ""; # 清空字段
proxy_hide_header Server;             # 隐藏响应头中的Server字段
​
3. 条件判断设置
if ($http_x_auth_token) {
    proxy_set_header Authorization "Bearer $http_x_auth_token";
}
​

七、配置生效流程图

八、注意事项

变量优先级：多个相同Header设置时，最后出现的配置生效
安全风险：避免直接传递未经验证的Header（如 X-Forwarded-For易被伪造）
性能影响：频繁修改Header可能增加代理延迟（建议仅传递必要信息）


通过以上配置方法，可灵活实现请求头的定制化处理，满足反向代理场景下的业务需求。建议在生产环境中配合日志分析工具（如 access_log）持续监控Header传递的准确性。