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块配置中,需要注意两个关键点:
- 因为
$是Nginx的变量解析前缀,要把头名中的$做转义(前面加反斜杠),让Nginx把\$name识别为字面字符串$name,作为转发后请求头的正式名称,而不是变量 - 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
相关产品推荐
相关产品推荐

