Nginx 中 proxy_set_header 如何根据条件动态添加-Nginx-PHP中文网

nginx 通过 map 指令在 http 块顶层定义条件变量，实现 proxy_set_header 的动态设置；map 性能好、语法清晰，可基于 $http_x_forwarded_for、$args 等变量判断，空值 header 自动忽略；禁止在 if 或 location 中直接使用 proxy_set_header。

nginx 中 proxy_set_header 如何根据条件动态添加

Nginx 本身不支持在 proxy_set_header 中直接写条件表达式（比如 if 块内使用），但可以通过变量 + map 指令实现安全、高效的动态 header 设置。

用 map 指令预定义条件变量

map 是 Nginx 最推荐的条件映射方式，它在请求处理早期就完成变量赋值，性能好且语法清晰。不能在 location 或 if 中定义 map，必须放在 http 块顶层。

例如：根据请求头 X-Forwarded-For 是否存在，动态设置后端的 X-Real-IP：

http {
    map $http_x_forwarded_for $real_ip {
        ""     $remote_addr;      # 空时用客户端真实 IP
        default $http_x_forwarded_for; # 非空时用代理链 IP
    }
<pre class="brush:php;toolbar:false;">server {
    location / {
        proxy_pass https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e;
        proxy_set_header X-Real-IP $real_ip;
    }
}

}

结合 $args 或 $request_uri 做路径/参数判断

可以基于 URL 参数或路径前缀控制 header 是否发送，比如只对带 ?debug=1 的请求添加调试头：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

map $args $debug_header {
    ~*debug=1 "1";
    default "";
}
<p>server {
location / {
proxy_pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a>;
proxy_set_header X-Debug $debug_header;</p><h1>若 $debug_header 为空字符串，该 header 实际不会发送给上游</h1><pre class="brush:php;toolbar:false;">}

}

Nginx 会自动跳过值为空的 proxy_set_header，所以无需额外判断。

避免在 if 块中使用 proxy_set_header

if 在 location 中使用会导致配置不可靠（Nginx 官方明确警告），且 proxy_set_header 在 if 内可能被忽略或行为异常。以下写法不推荐：

# ❌ 错误示例：if + proxy_set_header 组合不可靠
location / {
    if ($arg_env = "staging") {
        proxy_set_header X-Env "staging"; # 实际不会生效
    }
    proxy_pass https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e;
}