Nginx proxy_pass_request_args用法详解：控制代理请求参数传递的完整指南

什么是 proxy_pass_request_args

proxy_pass_request_args 是 Nginx ngx_http_proxy_module 内置指令，用来控制是否把客户端请求的查询参数（query string）传递给上游代理服务器。

很多人在配 proxy_pass 时发现：明明客户端带了 ?a=1&b=2，上游服务却收不到这些参数。问题往往就出在这个指令上。

默认值与基本用法

默认值：proxy_pass_request_args on;

值	行为
on	把客户端请求的查询参数原样传递给上游（默认）
off	不传递查询参数，上游收到的是不带 query string 的请求

# 默认行为，参数会被传递
location /api/ {
    proxy_pass http://backend:8080/;
    proxy_pass_request_args on;  # 可省略，默认就是on
}

on 和 off 的行为差异

proxy_pass_request_args on（默认）

客户端请求 /api/data?page=1&size=20，上游收到的请求 URI 包含 ?page=1&size=20。

proxy_pass_request_args off

同样请求，上游收到的请求 URI 为 /data，查询参数被丢弃。

location /api/ {
    proxy_pass http://backend:8080/;
    proxy_pass_request_args off;
}

这个指令和 proxy_pass_request_body 是"兄弟指令"，一个管查询参数，一个管请求体。

实际场景：什么时候需要设为 off

• 上游服务自己拼接参数：某些框架会从配置文件读取参数，不希望客户端传入的参数覆盖
• 安全隔离：不信任客户端传入的查询参数，由网关层统一控制
• 参数重写：配合 proxy_set_header 或重写 URI，用新参数替代原参数

与 $args / $query_string 的关系

很多人搞混 proxy_pass_request_args 和 $args 变量，两者作用层面不同：

指令/变量	作用
proxy_pass_request_args	控制是否传递原始查询参数给上游
$args	Nginx 变量，存储当前请求的查询参数，可被修改
proxy_set_header	自定义传递给上游的 HTTP 头

当你在 Nginx 配置里修改了 $args，proxy_pass_request_args on 传递的是修改后的 $args 值，而不是原始请求的参数。

location /api/ {
    set $args "from_nginx=1";  # 覆盖原始参数
    proxy_pass http://backend:8080/;
    proxy_pass_request_args on;  # 上游收到 ?from_nginx=1
}

常见错误与排查

错误1：proxy_pass URL 带路径时参数丢失

# 错误写法：参数可能丢失
location /api/ {
    proxy_pass http://backend:8080/app?fixed=1;
}

正确做法：让 Nginx 自动处理，不要手动在 proxy_pass 的 URL 里拼参数：

location /api/ {
    proxy_pass http://backend:8080/app;
    proxy_pass_request_args on;  # 默认就是on，显式写出更清晰
}

错误2：proxy_pass_request_args off 后上游拿不到参数

这是预期行为。如果上游需要参数，要么改为 on，要么在 Nginx 侧用 set $args 构造新参数再传递。

错误3：if 块里设置 proxy_pass_request_args 不生效

if 在 location 里有陷阱，建议用 map 指令替代：

map $request_uri $pass_args {
    ~^/api/  on;
    default   off;
}

location / {
    proxy_pass http://backend:8080/;
    proxy_pass_request_args $pass_args;
}

与 rewrite + proxy_pass 的配合

当使用 rewrite 重写了 URI 后再 proxy_pass，查询参数的行为需要特别注意：

# rewrite 后如果没加 ?，$args 会被自动附加
rewrite ^/api/(.*)$ /app/$1 last;

location /app/ {
    proxy_pass http://backend:8080/;
    # proxy_pass_request_args on（默认）
    # 上游会收到重写后的URI + 原始查询参数
}

如果 rewrite 时加了 ?（问号），查询参数会被清空：

# 问号会清空参数
rewrite ^/api/(.*)$ /app/$1? last;
# 上游收到的请求不带任何查询参数
# 此时 proxy_pass_request_args 即使是 on 也没参数可传

总结

• proxy_pass_request_args on 是默认行为，绝大多数场景不需要改
• 设为 off 适用于上游自己控制参数的场景
• 修改 $args 变量可以自定义传递给上游的参数内容
• rewrite 规则里的问号会影响参数传递，排查时优先检查 rewrite
• 避免在 if 块里设置该指令，用 map 更稳健

了解更多 Nginx 重定向和参数处理技巧，可以参考：Nginx rewrite保留查询参数完整教程、Nginx return和rewrite参数保留区别、Nginx rewrite和return参数行为差异。