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

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传递的准确性。

nginx proxy_set_header设置