处理 nginx 请求头重复问题,核心做法是明确区分“覆盖”与“追加”两种需求。若需保留所有值,使用 $http_header_name 变量配合 add_header;若需强制覆盖旧值,使用 proxy_set_header 或 set 指令。nginx 默认行为取决于具体指令,配置不当会导致后端收到多个相同键名的值。

如何确保后端只收到唯一的请求头值
要确保后端服务接收到的请求头是唯一的,必须使用 proxy_set_header 指令。该指令在代理阶段会直接替换上游传递的原始头部,从而消除重复。这是解决大多数因客户端发送重复头部导致后端解析错误的首选方案。

server {
listen 80;
server_name example.com;
location /api/ {
# 强制设置唯一值,忽略客户端原始 Header
proxy_set_header X-Custom-Header "unique-value";
# 其他必要配置
proxy_pass http://backend_servers;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
在上述配置中,无论客户端发送多少个 X-Custom-Header,Nginx 都会将其替换为 unique-value。后端应用将仅看到一个该头部。此方法适用于需要标准化输入、防止头部注入或简化后端逻辑的场景。注意,proxy_set_header 仅在匹配的位置块内生效,且会清除之前未显式设置的头部(除非使用 proxy_set_header ... default_value 语法或 Nginx Plus 特性,但标准版通常需显式声明所有需要的头部)。
如何保留并合并所有重复的请求头
当业务逻辑要求收集客户端发送的所有同名头部值时,应使用 $http_header_name 变量结合 add_header 指令。Nginx 内置的 $http_... 变量会自动将所有同名头部值用逗号连接成一个字符串。这种方式不会丢弃任何信息,适合审计、日志记录或需要完整上下文的情况。

server {
listen 80;
server_name example.com;
location /api/ {
# 获取所有 X-Custom-Header 的值,以逗号分隔
set $all_custom_headers $http_x_custom_header;
# 添加一个包含所有值的头部
add_header X-All-Custom-Headers $all_custom_headers always;
# 转发给后端
proxy_pass http://backend_servers;
proxy_set_header Host $host;
}
}
在此配置下,如果客户端发送了 X-Custom-Header: val1 和 X-Custom-Header: val2,变量 $http_x_custom_header 的值将是 val1, val2。随后,add_header 会将这个合并后的字符串作为新的 X-All-Custom-Headers 添加到响应或请求中(取决于使用场景,此处用于传递给后端需注意 add_header 通常用于响应头,若需传给后端应使用 proxy_set_header 配合变量)。更准确的做法是直接通过 proxy_set_header 传递合并后的变量:proxy_set_header X-Merged-Headers $http_x_custom_header;。这样后端就能接收到一个包含所有原始值的单一头部字段,其值为逗号分隔的字符串。这种方法避免了数据丢失,但后端需具备解析逗号分隔列表的能力。
当客户端发送空值或无效格式时会发生什么
当客户端发送空的请求头值(如 X-Empty:)或不符合 HTTP 规范的格式时,Nginx 的处理行为取决于所使用的指令。对于 proxy_set_header,如果源变量为空,Nginx 通常会省略该头部,或者设置为空字符串,具体取决于版本和配置。对于 $http_... 变量,如果头部存在但值为空,变量将为空字符串。这可能导致后端收到缺失的头部或空值,进而引发验证失败。建议在关键路径上增加条件判断或使用 map 指令进行预处理,以确保传递给后端的头部符合预期格式。


















