Nginx rewrite、return与proxy_pass配合使用差异：参数传递行为全解析

前言：rewrite、return、proxy_pass 三者混用时的参数迷局

在Nginx配置中，rewrite、return和proxy_pass是最常用的三个指令。单独用的时候大家都明白，但一旦放在同一个location里配合使用，参数传递就经常出问题——查询字符串莫名消失、请求体被丢弃、上游服务收不到参数。

这篇文章从实际配置场景出发，把三者在参数传递上的行为差异讲清楚，让你配Nginx时不再踩坑。

一、三个指令各自怎么处理参数

1. rewrite 的参数处理

rewrite的核心逻辑：用正则匹配URI，替换后生成新的请求。参数传递取决于你写不写问号：

# 不写问号 → 自动追加原参数
rewrite ^/old(.*)$ /new$1 last;

# 写了问号 → 用问号后的内容覆盖原参数
rewrite ^/old(.*)$ /new$1?foo=bar last;

# 问号后为空 → 清空所有参数
rewrite ^/old(.*)$ /new$1? last;

关键点：rewrite是内部重定向（除非替换部分以http/https开头），它不产生新的HTTP请求，而是在Nginx内部重新匹配location。

2. return 的参数处理

return直接返回响应或外部重定向，不会重新匹配location：

# 301重定向，浏览器发起新请求
return 301 https://$host$request_uri;

# 302重定向
return 302 https://$host$uri$is_args$args;

关键点：return产生的是外部重定向，浏览器收到后发起新请求。参数是否保留取决于你URL里有没有带上参数变量。

3. proxy_pass 的参数处理

proxy_pass把请求转发给上游服务器，参数行为取决于URI部分有没有路径：

# 不带路径 → 原样转发，参数保留
proxy_pass http://backend;

# 带路径 → 替换URI，但参数仍然保留
proxy_pass http://backend/api;

# 带路径且手动拼接参数
proxy_pass http://backend/api?$args;

关键点：proxy_pass默认会保留查询参数，除非你在URI末尾手动加了问号。

二、rewrite + proxy_pass：参数传递陷阱最多

场景1：rewrite后再proxy_pass

location /old {
    rewrite ^/old/(.*)$ /new/$1 break;
    proxy_pass http://backend;
}

这种写法没问题。rewrite用break标记，改写URI后不再重新匹配location，直接在同个location内执行proxy_pass。上游收到的请求URI是/new/xxx，查询参数保留。

场景2：rewrite用last标记 + proxy_pass

location /old {
    rewrite ^/old/(.*)$ /new/$1 last;
    # 这行不会执行！rewrite last会重新匹配location
    proxy_pass http://backend;
}

location /new {
    proxy_pass http://backend;
}

last标记会触发location重新匹配，所以/old里的proxy_pass不会执行。请求会被/new这个location处理。参数是否保留取决于rewrite规则有没有带问号。

场景3：proxy_pass带路径 + rewrite

location /api {
    rewrite ^/api/v1/(.*)$ /v2/$1 break;
    proxy_pass http://backend/service;
}

这里有个坑：proxy_pass带了路径/service，Nginx会把rewrite改写后的URI拼接上去，实际请求变成/service/v2/xxx。参数会保留，但路径拼接可能不是你想要的。

三、return + proxy_pass：不会同时执行

return和proxy_pass在同一个location里不会同时生效。return的优先级更高，一旦执行就直接返回响应：

location /api {
    return 301 https://new.example.com$request_uri;
    # 下面这行永远不会执行
    proxy_pass http://backend;
}

但在if块里，行为会变得微妙：

location /api {
    if ($arg_token = '') {
        return 401;
    }
    proxy_pass http://backend;
}

这种写法在某些Nginx版本中可能导致proxy_pass被跳过。建议用map+变量方式替代。

四、三者参数传递行为对比表

指令组合	查询参数	请求体(POST)	是否产生新请求
rewrite break + proxy_pass	保留（除非rewrite覆盖）	保留	否（内部转发）
rewrite last + proxy_pass	取决于新location	保留	否（内部重匹配）
return 301 + proxy_pass	不适用(return优先)	不适用	是（浏览器重定向）
return 302 + proxy_pass	不适用(return优先)	不适用	是（浏览器重定向）
if + return + proxy_pass	取决于条件分支	取决于条件分支	条件分支

五、实战建议

1. rewrite + proxy_pass 用 break 标记

大多数场景下，rewrite配合proxy_pass应该用break标记，确保改写后的URI直接在同一location内转发，避免location重匹配带来的意外。

2. 不要在同一个location混用return和proxy_pass

return会直接中断处理流程，proxy_pass永远不会执行。如果需要条件判断，用if+return做拦截，proxy_pass放在if外面。

3. proxy_pass带路径时要小心rewrite

当proxy_pass带了URI路径时，rewrite改写后的URI会被拼接而非替换。如果不确定，可以不带路径，让proxy_pass完整传递rewrite后的URI。

4. 验证参数是否正确传递

# 在上游服务打印收到的请求
curl -v "http://localhost/api/test?foo=bar"

# 用Nginx日志记录$request_uri确认
log_format debug '$request_uri $args';
access_log /var/log/nginx/debug.log debug;

六、常见错误配置及修复

错误1：rewrite后proxy_pass路径拼接问题

# 错误：会产生 /backend/new/xxx 而不是 /new/xxx
location /old {
    rewrite ^/old/(.*)$ /new/$1 break;
    proxy_pass http://backend/backend;
}

# 修复：不带路径
location /old {
    rewrite ^/old/(.*)$ /new/$1 break;
    proxy_pass http://backend;
}

错误2：if块内proxy_pass失效

# 可能出问题
location /api {
    if ($http_x_token = '') {
        return 403;
    }
    proxy_pass http://backend;
}

# 更可靠的方式：用map + error_page
map $http_x_token $auth_status {
    "" 403;
    default 0;
}

location /api {
    if ($auth_status = 403) {
        return 403;
    }
    proxy_pass http://backend;
}

总结

rewrite、return和proxy_pass三者配合使用时，核心要记住三点：

• rewrite + proxy_pass：用break标记，注意proxy_pass是否带路径
• return + proxy_pass：不要混用，return会直接中断
• 参数传递：rewrite的问号决定参数覆盖/保留，proxy_pass默认保留参数

搞清楚这三点，Nginx配置就不会再出参数丢失的幺蛾子了。

相关文章

• Nginx rewrite和return区别详解：重定向到底该用哪个？
• Nginx return和rewrite在location中谁先执行？优先级规则全解析
• Nginx rewrite和return重定向区别详解：什么场景用哪个、怎么配才正确