You need to enable JavaScript to run this app. Nginx如何转发名称带有$符号的HTTP自定义请求头
优惠活动
大模型
产品
解决方案
定价
更多

Nginx如何转发名称带有$符号的HTTP自定义请求头

Nginx 透传携带$符号自定义请求头的配置方法

根因说明

请求头在反向代理环节丢失,一般是两个常见问题叠加导致:

  • Nginx 默认会过滤掉名称包含下划线的入站请求头,这类头会在请求刚进入Nginx时就被丢弃,根本走不到转发流程
  • Nginx 解析proxy_set_header的参数时,会优先把$开头的片段识别为内置变量。直接照搬常见示例里的proxy_set_header $name $http_$name;写法既没法把$name固定为字面的请求头名,也没法通过规则正确取到请求头的实际值

正确配置步骤

1. 放开Nginx对下划线请求头的接收限制

如果你的自定义请求头名中包含下划线字符,必须在http块或者对应server块下开启配置,否则入站阶段就会丢头:

underscores_in_headers on;

哪怕当前你的头名没有下划线,也建议加上这个配置,避免后续新增带下划线的自定义头时踩坑。

2. 编写正确的反向代理透传规则

在对应的location块配置中,需要注意两个关键点:

  1. 因为$是Nginx的变量解析前缀,要把头名中的$做转义(前面加反斜杠),让Nginx把\$name识别为字面字符串$name,作为转发后请求头的正式名称,而不是变量
  2. Nginx 生成入站请求头的内置取值变量有固定规则:原头名全部转小写,所有非字母数字的字符(包括$、-、下划线)统一替换为下划线,最后加上http_前缀。如果原头名是纯$name,其中的$会被替换为下划线,对应的取值变量是$http__name(http_后接两个下划线)

完整的可用配置示例:

location /api/ {
    proxy_pass         http://127.0.0.1:8081/;
    proxy_redirect     off;
    proxy_set_header   Host $host;
    # 转义$作为字面头名,取到对应入站头的实际值
    proxy_set_header   \$name $http__name;
}

常见踩坑提醒

  • 不要直接照搬示例里的错误写法:proxy_set_header $name $http_$name; 这种写法会把第一个参数位置的$name解析成Nginx内置变量$name(绝大多数场景下这个变量为空),最终设置的转发头名根本不是预期的$name;同时第二个参数会拼接$http_和系统变量$name的值,几乎取不到正确的头内容
  • 如果你的自定义头名有其他前缀(比如X-App-$name),可以手动按照Nginx的变量规则换算取值变量:把原头名转小写,所有非字母数字的字符替换为下划线,最后加http_前缀即可。比如X-App-$name对应的取值变量是$http_x_app__name

内容的提问来源于stack exchange,提问作者swd1117

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.21 08:15:10