ngx_http_rewrite_module

This module makes it possible to change URI using regular expressions, and to redirect and select configuration depending on variables.

该模块允许使用正则表达式改变URI，并且根据变量来转向以及选择配置。

If the directives of this module are given at the server level, then they are carried out before the location of the request is determined. If in that selected location there are further rewrite directives, then they also are carried out. If the URI changed as a result of the execution of directives inside location, then location is again determined for the new URI.

如果在server级别设置该选项，那么他们将在location之前生效。如果在location还有更进一步的重写规则，location部分的规则依然会被执行。如果这个URI重写是因为location部分的规则造成的，那么location部分会再次被执行作为新的URI。

This cycle can be repeated up to 10 times, after which Nginx returns a 500 error.

这个循环会执行10次，然后Nginx会返回一个500错误。

Directives

• [#break break]
• [#if if]
• [#return return]
• [#rewrite rewrite]
• [#set set]
• [#uninitialized_variable_warn uninitialized_variable_warn]

Template:Anchor

break

语法: break

默认值: none

作用域: server, location, if

Completes the current set of rules. 作用是完成当前的规则列

示例:

if ($slow) {
: limit_rate  10k;
: break;
}

Template:Anchor

if

语法: if (condition) { ... }

默认: none

作用域: server, location

Checks the truth of a condition. If the condition evaluates to true, then the code indicated in the curly braces is carried out and the request is processed in accordance with the configuration within the following block. Configuration inside directive if is inherited from the previous level.

They can be assigned as the condition: 条件语句可以使下列的几种：

• the name of variable; false values are: empty string "", or any string starting with "0";

 一个变量的名称；如果变量的值为空字符串""或者任何以0开始的字符串，则表示条件语句的值为假

• the comparison of variable with the line with using the = and != operators;
• pattern matching with regular expressions using the symbols ~* and ~:

1. 正则表达式形式的模式匹配，如~*和~

• ~ is case-sensitive match;
• ‘~’表示大小写敏感的匹配
• ~* specifies a case-insensitive match (firefox matches FireFox)
• ‘~*’表示大小写不敏感的匹配（例如：“firefox”字符串可以成功匹配“FireFox”）
• !~ and !~* mean the opposite, "doesn't match"
•  !~和!~*代表跟后面的正则匹配规则相反的规则，表示不能匹配当前正则表达式规则的字符串执行后面的处理语句
• checking for the existence of a file using the -f and !-f operators;使用-f参数以及!-f参数检测一个文件是否存在
• checking existence of a directory using the -d and !-d operators;使用-d参数以及!-d参数检测一个目录（路径）是否存在
• checking existence of a file, directory or symbolic link using the -e and !-e operators;

使用-e以及!-e检测是否存在一个文件，一个目录或者一个符号链接。

• checking whether a file is executable using the -x and !-x operators.使用-x以及!-x检测一个文件是否可执行

Parts of the regular expressions can be in parentheses, whose value can then later be accessed in the $1 to $9 variables.

正则表达式部分可以嵌套，表达式后面的部分如果用到前面的表达式可以用 $1 到$9 变量表示。

Examples of use: 例子如下：

if ($http_user_agent ~ MSIE) {
: rewrite  ^(.*)$  /msie/$1  break;
}
if ($http_cookie ~* "id=([^;] +)(?:;|$)" ) {
: set  $id  $1;
}
if ($request_method = POST ) {
: return 405;
}
if (!-f $request_filename) {
: break;
: proxy_pass  http://127.0.0.1;
}
if ($slow) {
: limit_rate  10k;
}
if ($invalid_referer) {
: return   403;
}

The value of the built-in variable $invalid_referer is given by the directive valid_referers.

Template:Anchor

return

语法: return code

默认值: none

作用域: server, location, if

This directive concludes execution of the rules and returns the status code indicated to client. It is possible to use the following values: 204, 400, 402-406, 408, 410, 411, 413, 416 and 500-504. Furthermore, nonstandard code 444 closes the connection without sending any headers.

这个指令根据规则的执行情况，返回一个状态值给客户端。可使用值包括：204，400，402-406，408，410，411，413，416以及500-504。也可以发送非标准的444代码-未发送任何头信息下结束连接。

Template:Anchor

rewrite

语法: rewrite regex replacement flag

默认: none

作用域: server, location, if

This directive changes URI in accordance with the regular expression and the replacement string. Directives are carried out in order of appearance in the configuration file.

这个指令根据正则表达式或者待替换的字符串来更改URI。指令根据配置文件中的先后顺序执行生效。

Be aware that the rewrite regex only matches the relative path instead of the absolute URL. If you want to match the hostname, you should use an if condition, like so:

注意：重写规则只匹配相对路径（不包括绝对的URL）。如果你想配对主机名，你应该使用if语句，如下：

if ($host ~* www\.(.*)) {
: set $host_without_www $1;
: rewrite ^(.*)$ http://$host_without_www$1 permanent; # $1 contains '/foo', not 'www.mydomain.com/foo'
}

Flags make it possible to end the execution of rewrite directives. flag标记可以停止重定向规则的执行

If the replacement string begins with http:// then the client will be redirected, and any further rewrite directives are terminated. 如果替换字符串以“http:”开始，客户端会被重定向，而且其他的重定向规则都会被终止。

Flags can be any of the following: 可用的flag标记有：

• last - completes processing of rewrite directives, after which searches for corresponding URI and location

 完成该rewrite规则的执行，之后查找符合的URI和location

• break - completes processing of rewrite directives

 终止匹配，不再匹配后面的规则

• redirect - returns temporary redirect with code 302; it is used if the substituting line begins with http://

 返回302临时重定向，当替代行以http:开始时可以使用，地址栏会显示跳转后的地址

• permanent - returns permanent redirect with code 301

 返回301永久重定向

Note that if an redirect is relative (has no host part), then when redirecting Nginx uses the "Host" header if the header match name of server_name directive or the first name of server_name directive, if the header does not match or is absent. If no server_name is set, then the local hostname is used. If you want Nginx to always use the "Host" header, you can use a wildcard "*" server_name (but see the restrictions on doing so).Example:

rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  last;
rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   last;
return   403;

But if we place these directives in location /download/, then it is necessary to replace flag "last" by "break", otherwise nginx will hit the 10 cycle limit and return error 500:

1. 如果我们将当前的匹配规则使用在/download/目录下，就要将"last"替换为"break"了。否则nginx就会达到10次循环的上限，然后返回个500错误

location /download/ {
: rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;
: rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   break;
: return   403;
}

If in the line of replacement arguments are indicated, then the rest of the request arguments are appended to them. To avoid having them appended, place a question mark as the last character:

: rewrite  ^/users/(.*)$  /show?user=$1?  last;

注: 对花括号( { 和 } )来说, 他们既能用在重定向的正则表达式里，也是用在配置文件里分割代码块, 为了避免冲突, 正则表达式里带花括号的话，应该用双引号（或者单引号）包围。比如，要将类似以下的url

 
/photos/123456 

重定向到：

 
/path/to/photos/12/1234/123456.png 

可以用以下方法 (注意双引号):

rewrite  "/photos/([0-9] {2})([0-9] {2})([0-9] {2})" /path/to/photos/$1/$1$2/$1$2$3.png; 

Template:Anchor

set

syntax: set variable value

default: none

context: server, location, if

Directive establishes value for the variable indicated. As the value it is possible to use a text, variables and their combination.

Template:Anchor

uninitialized_variable_warn

syntax: uninitialized_variable_warn on|off

default: uninitialized_variable_warn on

context: http, server, location, if

Enables or disables logging of warnings about noninitialized variables.

Internally, the rewrite directives are compiled at the time the configuration file is loaded into internal codes, usable during the request by the interpreter.

This interpreter is a simple stack virtual machine. For example, the directive:

location /download/ {
: if ($forbidden) {
: return   403;
: }
: if ($slow) {
: limit_rate  10k;
: }
: rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;
}

will be compiled into this sequence:

: variable $forbidden
: checking to zero
: recovery 403
: completion of entire code
: variable $slow
: checking to zero
: checkings of regular expression
: copying "/"
: copying $1
: copying "/mp3/"
: copying $2
: copying "..mpe"
: completion of regular expression
: completion of entire sequence

Note that there is no code for directive limit_rate, since it does not refer to module ngx_http_rewrite_module. The "if" block exists in the same part of the configuration as the "location" directive.

If $slow is true, then what's inside the "if" block is evaluated, and in this configuration limit_rate it is equal to 10k.

Directive:

: rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;

It is possible to reduce the sequence, if in the regular expression we include the first slash inside the parentheses:

: rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;

then the sequence will appear like this:

: checking regular expression
: copying $1
: copying "/mp3/"
: copying $2
: copying "..mpe"
: completion of regular expression
: completion of entire code

References

Original Documentation