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 和 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

• 上游服务自己拼接参数：不希望客户端传入的参数覆盖
• 安全隔离：由网关层统一控制参数
• 参数重写：用新参数替代原参数

与 $args 的关系

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

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;
}

正确做法：不要手动在 proxy_pass 的 URL 里拼参数。

location /api/ {
    proxy_pass http://backend:8080/app;
}

错误2：if 块里设置不生效

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 配合时的参数陷阱

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

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

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

rewrite ^/api/(.*)$ /app/$1? last;
# 上游收到的请求不带任何查询参数

总结

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

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