在 nginx 中转发自定义请求头,核心做法是使用 proxy_set_header 指令将客户端发送的原始 header 复制到后端服务。具体操作是在 location 块中配置 proxy_set_header x-custom-header $http_x_custom_header;,这样后端就能通过标准 http 协议获取到该值。如果请求头中包含特殊字符或需要保留原有大小写,nginx 会自动处理转换逻辑,确保数据准确传递。

如何转发包含连字符的自定义 Header
当客户端发送如 X-Request-ID 这样的带连字符请求头时,Nginx 会将其转换为内部变量 $http_x_request_id。只需在配置中显式声明该变量的映射关系即可实现透传。这种机制允许后端应用直接读取客户端提供的追踪 ID 或认证令牌,无需修改 Nginx 源码或启用额外模块。

server {
listen 80;
server_name example.com;
location /api/ {
proxy_pass http://backend_server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Request-ID $http_x_request_id;
}
}
预期结果:当客户端发送 X-Request-ID: abc-123 时,后端收到的请求头中将包含 X-Request-ID: abc-123。若客户端未发送该头,后端则收不到对应字段,不会显示为空字符串或默认值。
如何处理非标准或二进制编码的请求头
对于非 ASCII 字符或经过 Base64 编码的自定义 Header,Nginx 默认按文本流处理,不会自动解码。开发者需在后端代码中自行解析,或在 Nginx 中使用 map 指令预处理。此场景下,重点在于确保 Nginx 不丢弃非法字符,而是原样转发给上游服务。

map $http_x_binary_data $custom_binary {
default $http_x_binary_data;
"" "";
}
server {
listen 80;
server_name example.com;
location /upload/ {
proxy_pass http://backend_server;
proxy_set_header X-Binary-Payload $custom_binary;
}
}
预期结果:若客户端发送 X-Binary-Data: dGVzdA==,后端将收到 X-Binary-Payload: dGVzdA==。Nginx 不做任何内容转换,仅做变量赋值。若输入为空,输出也为空,后端可据此判断是否缺失必要参数。
基于 proxy_set_header 覆盖默认行为的具体问题
当同时使用 proxy_set_header 和 proxy_pass 时,若未显式设置 Host 头,Nginx 会默认使用 $proxy_host 而非 $host。这可能导致后端服务器无法正确识别虚拟主机。因此,必须显式指定 proxy_set_header Host $host; 以保证兼容性。


















