Nginx如何在存在指定特殊请求头时为请求自动追加URL参数

不需要额外第三方模块，用Nginx原生配置即可实现需求，推荐用map做条件匹配，逻辑更稳定。

完整配置示例 #

1. 首先在server块层级之外（一般放在http块内，和站点server配置平级）定义条件匹配规则：

# 匹配自定义请求头，判断是否需要追加参数
map $http_x_my_special $append_special_param {
    default  "";
    "true"   "x-my-special=true";
}

说明：Nginx读取自定义请求头的变量格式为$http_ + 头名称全小写，头名称里的中划线会自动转换为下划线，所以x-my-special头对应读取变量就是$http_x_my_special。

2. 在需要生效的location块里拼接查询参数，兼容原请求无查询参数的场景：

location / {
    # 先读取原始查询参数
    set $modified_args $args;

    # 需要追加参数时，自动适配连接符
    if ($append_special_param != "") {
        set $modified_args "${modified_args}&${append_special_param}";
        # 原请求无参数时，去掉开头多余的&
        if ($args = "") {
            set $modified_args $append_special_param;
        }
    }

    # 按实际部署场景选择对应转发规则
    # 反向代理到后端服务用这个
    proxy_pass http://你的后端服务地址$uri?$modified_args;
    
    # 如果是对接FastCGI（比如PHP站点），替换QUERY_STRING参数即可
    # fastcgi_param QUERY_STRING $modified_args;
}

注意事项 #

• 配置修改完成后先执行nginx -t校验语法，确认无报错后执行nginx -s reload重载配置生效
• map匹配比直接在location中嵌套多层if判断性能更好，也能避开Nginx "if is evil"的已知逻辑陷阱，不要把所有头判断逻辑全堆在location的if块里
• 以上配置不会判断原参数中是否已经存在x-my-special，如果需要避免重复追加，可以在if逻辑里加一层$args不包含目标参数的判断
• 如果你服务器上的Nginx已经安装了ngx_set_misc第三方模块，还可以用set_if_empty等指令简化参数拼接逻辑，默认官方源安装的Nginx不带该模块，新手直接用上述原生配置即可满足需求。

内容的提问来源于stack exchange，提问作者mickmack