nginx配置指令rewrite的last、break、redirect、permanent参数详解

配置示例

注：示例中使用了echo模块，这样可以直接看到响应的内容，以及变量修改情况

server {
    listen       80;
    server_name  example.com;
    set $flag    "org";

    location /noflag/ {
        set $flag "noflag";
        rewrite ^/noflag/(.*) /test/$1?capture=$1;
        set $flag "rewrite noflag";
        echo flag=[$flag];
        echo "noflag page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location /last/ {
        set $flag "last";
        rewrite ^/last/(.*) /test/$1?capture=$1 last;
        set $flag "rewrite last";
        echo flag=[$flag];
        echo "last page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location /break/ {
        set $flag "break";
        rewrite ^/break/(.*) /test/$1?capture=$1 break;
        set $flag "rewrite break";
        echo flag=[$flag];
        echo "break page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location /break_set/ {
        set $flag "break_set";
        rewrite ^/break_set/(.*) /test/$1?capture=$1 break;
        set $flag "rewrite break_set";
        echo flag=[$flag];
    }

    location /html/ {
        rewrite ^/html/(.*) /test/$1?capture=$1 break;
    }
    
    location /redirect/ {
        set $flag "redirect";
        rewrite ^/redirect/(.*) /test/$1?capture=$1 redirect;
        set $flag "rewrite redirect";
        echo flag=[$flag];
        echo "redirect page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location /permanent/ {
        set $flag "permanent";
        rewrite ^/permanent/(.*) /test/$1?capture=$1 permanent;
        set $flag "rewrite permanent";
        echo flag=[$flag];
        echo "permanent page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location /test/ {
        echo flag=[$flag];
        echo "test page";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }

    location / {
        echo flag=[$flag];
        echo "location /";
        echo request=[$request];
        echo request_uri=[$request_uri];
        echo uri=[$uri] args=[$args];
        echo document_uri=[$document_uri] query_string=[$query_string];
    }
}

请求演示

●无标志
请求URL：http://example.com/noflag/a.html?key=value
结果：
flag=[rewrite noflag]
test page
request=[GET /noflag/a.html?key=value HTTP/1.1]
request_uri=[/noflag/a.html?key=value]
uri=[/test/a.html] args=[capture=a.html&key=value]
document_uri=[/test/a.html] query_string=[capture=a.html&key=value]
说明：

1. 将原始请求/noflag/a.html?key=value重写为/test/a.html?capture=a.html&key=value
2. 执行了后续的ngx_http_rewrite_module模块的指令set，将flag修改为rewrite noflag
3. 没有执行后续的echo指令，而是发起了内部请求。新的请求匹配了location /test/，该location返回了响应。
4. rewrite指令改变了变量$uri（$document_uri）、$args（$query_string），但不会改变$request、$request_uri，这些变量可以输出到access log中。
5. nginx access log生成1条日志

●last
请求URL：http://example.com/last/a.html?key=value
结果：
flag=[last]
test page
request=[GET /last/a.html?key=value HTTP/1.1]
request_uri=[/last/a.html?key=value]
uri=[/test/a.html] args=[capture=a.html&key=value]
document_uri=[/test/a.html] query_string=[capture=a.html&key=value]
说明：

1. 将原始请求/last/a.html?key=value重写为/test/a.html?capture=a.html&key=value
2. 不再执行后续的rewrite 模块指令，没有修改flag的值。这是last标志和不加标志的区别。
3. 没有执行后续的echo指令，而是发起了内部请求。新的请求匹配了location /test/，该location返回了响应。
4. rewrite指令改变了变量$uri（$document_uri）、$args（$query_string），但不会改变$request、$request_uri，这些变量可以输出到access log中。
5. nginx access log生成1条日志

●break
请求URL：http://example.com/break/a.html?key=value
结果：
flag=[break]
break page
request=[GET /break/a.html?key=value HTTP/1.1]
request_uri=[/break/a.html?key=value]
uri=[/test/a.html] args=[capture=a.html&key=value]
document_uri=[/test/a.html] query_string=[capture=a.html&key=value]
说明：

1. 将原始请求/break/a.html?key=value重写为/test/a.html?capture=a.html&key=value
2. 不再执行后续的rewrite 模块指令，没有修改flag的值。
3. 不发起新的请求。继续执行本location中的后续处理阶段，即返回了响应。这是break标志与last标志的区别。
4. rewrite指令改变了变量$uri（$document_uri）、$args（$query_string），但不会改变$request、$request_uri，这些变量可以输出到access log中。
5. nginx access log生成1条日志

●break + set指令
请求URL：http://example.com/break_set/a.html?key=value
结果：
flag=[break_set]
说明：

1. 将原始请求/break_set/a.html?key=value重写为/test/a.html?capture=a.html&key=value，由于rewrite的flag参数是break，不发起新的请求也不再执行后面的rewrite模块的指令。继续执行本location中的后续处理阶段，即返回了响应。
2. rewrite指令改变了变量$uri（$document_uri）、$args（$query_string），但不会改变$request、$request_uri，这些变量可以输出到access log中。
3. nginx access log生成1条日志

●break后无指令
请求URL：http://example.com/html/a.html?key=value
结果：
404 Not Found
说明：

1. 将原始请求/html/a.html?key=value重写为/test/a.html?capture=a.html&key=value，由于使用了break参数，所以不会发起新的请求，由于没有其他指令，所以会执行该location下的默认的content阶段的指令，即尝试找/test/a.html（这个路径不是操作系统上的路径，而是nginx静态文件的路径，默认是以nginx安装目录下的html为根目录）这个html页面并输出内容，由于该页面不存在，所以返回404。
2. rewrite指令改变了变量$uri（$document_uri）、$args（$query_string），但不会改变$request、$request_uri，这些变量可以输出到access log中。
3. nginx access log生成1条日志

●redirect
请求URL：http://example.com/redirect/a.html?key=value
结果：
flag=[org]
test page
request=[GET /test/a.html?capture=a.html&key=value HTTP/1.1]
request_uri=[/test/a.html?capture=a.html&key=value]
uri=[/test/a.html] args=[capture=a.html&key=value]
document_uri=[/test/a.html] query_string=[capture=a.html&key=value]
说明：

1. 直接返回客户端302，并将重写后的URL（http://example.com/test/a.html?capture=a.html&key=value）放到响应头的Location字段中。
2. rewrite没有修改$uri（$document_uri）、$args（$query_string）、$request、$request_uri。access log中输出的第一个请求的上述变量没有修改。
3. 如果是浏览器访问，浏览器会使用rewrite后的URL重新发起请求，并收到上述结果。
4. nginx access log生成2条日志，一次是原请求的，另一次是客户端重新发起的请求。

●permanent
请求URL：http://example.com/permanent/a.html?key=value
结果：
flag=[org]
test page
request=[GET /test/a.html?capture=a.html&key=value HTTP/1.1]
request_uri=[/test/a.html?capture=a.html&key=value]
uri=[/test/a.html] args=[capture=a.html&key=value]
document_uri=[/test/a.html] query_string=[capture=a.html&key=value]
说明：

1. 直接返回客户端301，并将重写后的URL（http://example.com/test/a.html?capture=a.html&key=value）放到响应头的Location字段中。
2. rewrite没有修改$uri（$document_uri）、$args（$query_string）、$request、$request_uri。access log中输出的第一个请求的上述变量没有修改。
3. 如果是浏览器访问，浏览器会使用rewrite后的URL重新发起请求，并收到上述结果。
4. nginx access log生成2条日志，一次是原请求的，另一次是客户端重新发起的请求。