nginx 官网文档翻译--重定向

nginx 重定向模块简介

The ngx_http_rewrite_module module is used to change request URI using PCRE regular expressions, return redirects, and conditionally select configurations.

The ngx_http_rewrite_module module directives are processed in the following order:

• the directives of this module specified on the server level are executed sequentially;
• repeatedly:
  • a location is searched based on a request URI;
  • the directives of this module specified inside the found location are executed sequentially;
  • the loop is repeated if a request URI was rewritten, but not more than 10 times.

ngx_http_rewrite_module--nginx 的 http 重定向模块通过使用 PCRE(Perl Compatible Regular Expressions) 正则，来改变请求 URI，返回重定向，以及有条件的选择配置。

nginx的重定向模块指令按照以下步骤处理：

• 在服务器级别指定的这个模块的指令被连续执行
• 不停地：
  • （根据请求URI）搜索一个 location
  • 在找到的 location 中指定的（这个模块的）指令被连续执行
  • 如果一个请求 URI 被重写，那么这个循环就重复，但不能超过10次

具体指令

Syntax:    break;
Default:    —
Context:    server, location, if

Stops processing the current set of ngx_http_rewrite_module directives.

If a directive is specified inside the location, further processing of the request continues in this location.

Example:

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

语法： break；
默认： ——
Context： server,location,if

停止处理当前重定向的指令集

如果在 location 中一个指令被指定，继续在这个 location 中进一步的处理这个请求。

示例：

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

Syntax:    if (condition) { ... }
Default:    —
Context:    server, location

The specified condition is evaluated. If true, this module directives specified inside the braces are executed, and the request is assigned the configuration inside the if directive. Configurations inside the if directives are inherited from the previous configuration level.

A condition may be any of the following:

• a variable name; false if the value of a variable is an empty string or “0”;
  • Before version 1.0.1, any string starting with “0” was considered a false value.
• comparison of a variable with a string using the “=” and “!=” operators;
• matching of a variable against a regular expression using the “~” (for case-sensitive matching) and “~*” (for case-insensitive matching) operators. Regular expressions can contain captures that are made available for later reuse in the $1..$9 variables. Negative operators “!~” and “!~*” are also available. If a regular expression includes the “}” or “;” characters, the whole expressions should be enclosed in single or double quotes.
• checking of a file existence with the “-f” and “!-f” operators;
• checking of a directory existence with the “-d” and “!-d” operators;
• checking of a file, directory, or symbolic link existence with the “-e” and “!-e” operators;
• checking for an executable file with the “-x” and “!-x” operators.

Examples:

if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}

if ($request_method = POST) {
    return 405;
}

if ($slow) {
    limit_rate 10k;
}

if ($invalid_referer) {
    return 403;
}

A value of the $invalid_referer embedded variable is set by the valid_referers directive.

语法：     if (condition) { ... }
默认： ——
Context： server,location

判断 condition，如果为真，花括号中的模块指令被执行，并且请求被分配给 if 指令中的配置。if 指令中的配置是从上一级的配置中继承。

判断条件可能是下面当中的一个：

• 一个变量名；如果变量是一个空字符串或者为0，那么为 false;
  • 在 1.0.1 版本之前，任何以0开头的字符串都会被认为是 false 值
• 用"="和"!="操作符来比较一个变量；
• 通过正则表达式匹配变量（使用 "~"（大小写敏感匹配）），（使用 "~*"（大小写不敏感匹配））。....注：这段需要重新翻译
• 通过 "-f"和"!-f"操作符检查文件扩展名
• 通过 "-d"和"!-d"操作符检查目录扩展名
• 通过 "-e"和"!-e"操作符检查文件，目录，或是一个符号连接
• 通过 "-x"和"!-x"操作符检查是否是一个可执行文件

示例：

if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}

if ($request_method = POST) {
    return 405;
}

if ($slow) {
    limit_rate 10k;
}

if ($invalid_referer) {
    return 403;
}

包含在变量中的 $invalid_referer的值可以通过 valid_referers设置。

Syntax:    return code [text];
return code URL;
return URL;
Default:    —
Context:    server, location, if

Stops processing and returns the specified code to a client. The non-standard code 444 closes a connection without sending a response header.

Starting from version 0.8.42, it is possible to specify either a redirect URL (for codes 301, 302, 303, and 307), or the response body text (for other codes). A response body text and redirect URL can contain variables. As a special case, a redirect URL can be specified as a URI local to this server, in which case the full redirect URL is formed according to the request scheme ($scheme) and the server_name_in_redirect and port_in_redirect directives.

In addition, a URL for temporary redirect with the code 302 can be specified as the sole parameter. Such a parameter should start with the “http://”, “https://”, or “$scheme” string. A URL can contain variables.

• Only the following codes could be returned before version 0.7.51: 204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504.
• The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.

See also the error_page directive.

语法:    return code [text];
return code URL;
return URL;
默认:    —
Context:    server, location, if

停止处理并且向客户端返回指定的 返回码 ，非标准的 444 返回码 会在不发送一个 response header 情况下关闭连接。

从 0.8.42 版本开始，我们已经能够指定一个重定向的 URL（针对301，302，303，或者是307），或是指定一个 response body text（针对其他 code ）。

response body text 或是 重定向 URL 可以包含变量。一种特殊的情况下，重定向URL可以作为 URI 指定本地服务器 ，在这种情况下，完整的重定向的 URL 会(根据请求（$scheme）模式，server_name_in_redirect 和 port_in_redirect) 指令来生成。

此外， (带有302返回码的用于临时重定向的) URL可以被指定为唯一的参数。这样的参数应该以"http://"，"https://"，或者是"$scheme"开头。URL 可以包含变量。

在0.7.51版本前只有以下的返回码可以被返回： 204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504。 直到1.1.16和1.0.13版本，307返回码才被作为重定向。

也可以看看 error_page 指令，获取更多信息。

Syntax:    rewrite regex replacement [flag];
Default:    —
Context:    server, location, if

If the specified regular expression matches a request URI, URI is changed as specified in the replacement string. The rewrite directives are executed sequentially in order of their appearance in the configuration file. It is possible to terminate further processing of the directives using flags. If a replacement string starts with “http://” or “https://”, the processing stops and the redirect is returned to a client.

An optional flag parameter can be one of:

• last
  • stops processing the current set of ngx_http_rewrite_module directives and starts a search for a new location matching the changed URI;
• break
  • stops processing the current set of ngx_http_rewrite_module directives as with the break directive;
• redirect
  • returns a temporary redirect with the 302 code; used if a replacement string does not start with “http://” or “https://”;
• permanent
  • returns a permanent redirect with the 301 code.

语法:    rewrite regex replacement [flag];
默认:    —
Context:    server, location, if

如果指定的正则匹配了一个请求 URI ，URI会以替代字符串中指定那样变化。重定向指令会按照在配置文件中的顺序连续执行。可以通过 flags 来终止指令的进一步处理。如果替代字符串以“http://” 或是 “https://” 开头，那么处理会停止，重定向也会返回给客户端。

可选的 flag 参数可以是以下几个中的一个：

• last
  • 停止处理当前 ngx_http_rewrite_module 指令集，并且搜索新的 location 来匹配改变的 URI。
• break
  • 停止处理当前 ngx_http_rewrite_module 指令集与 break 指令
• redirect
  • 返回一个带有302返回码的临时重定向；如果替代字符串以“http://” 或是 “https://” 开头就启用
• permanent
  • 返回一个带有301返回码的永久重定向

The full redirect URL is formed according to the request scheme (scheme) and the server_name_in_redirect and port_in_redirect directives.

Example:

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

But if these directives are put inside the “/download/” location, the last flag should be replaced by break, or otherwise nginx will make 10 cycles and return the 500 error:

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

If a replacement string includes the new request arguments, the previous request arguments are appended after them. If this is undesired, putting a question mark at the end of a replacement string avoids having them appended, for example:

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

If a regular expression includes the “}” or “;” characters, the whole expressions should be enclosed in single or double quotes.

完整的重定向的 URL 会(根据请求（scheme）模式，server_name_in_redirect 和 port_in_redirect) 指令来生成。

示例：

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

如果这些指令被放置在 "/download/" location，"last" flag 应该通过 break 被替换，或者 nginx 会进行10次循环，并且返回 500 错误码。

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

如果替换字符串包含新的请求参数，先前的请求参数会被添加到它们后面。如果不是预期的情况，就在替代字符串最后面添加一个问号以避免它们被附加上，举例来说：

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

如果，正则表达式中包含字符 "}" 或是 ";" ，整个表达式应该包含在单引号或双引号。

Syntax:    rewrite_log on | off;
Default:    
rewrite_log off;
Context:    http, server, location, if

Enables or disables logging of ngx_http_rewrite_module module directives processing results into the error_log at the notice level.

Syntax:    set $variable value;
Default:    —
Context:    server, location, if
Sets a value for the specified variable. The value can contain text, variables, and their combination.

Syntax:    uninitialized_variable_warn on | off;
Default:    
uninitialized_variable_warn on;
Context:    http, server, location, if

Controls whether warnings about uninitialized variables are logged.

语法:    rewrite_log on | off;
默认:    rewrite_log off;
Context:    http, server, location, if

在 notice 级别是否启用将（ngx_http_rewrite_module模块指令的处理结果）记录到 error_log 中。

语法:    set $variable value;
默认:    —
Context:    server, location, if

为指定变量设置一个值，该值可以包含文本、变量和它们的组合。

语法:    uninitialized_variable_warn on | off;
默认:    
uninitialized_variable_warn on;
Context:    http, server, location, if

控制（当记录到未初始化的变量的时候）是否发车警告

内部实现

The ngx_http_rewrite_module module directives are compiled at the configuration stage into internal instructions that are interpreted during request processing. An interpreter is a simple virtual stack machine.

For example, the directives

location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

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

will be translated into these instructions:

variable $forbidden
check against zero
    return 403
    end of code
variable $slow
check against zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code

Note that there are no instructions for the limit_rate directive above as it is unrelated to the ngx_http_rewrite_module module. A separate configuration is created for the if block. If the condition holds true, a request is assigned this configuration where limit_rate equals to 10k.

The directive

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

can be made smaller by one instruction if the first slash in the regular expression is put inside the parentheses:

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

The corresponding instructions will then look like this:

match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code

ngx_http_rewrite_module模块指令在配置阶段被编译为内部指令，在请求处理阶段被解释。解释器是一个简单虚拟堆栈机。

举例来说，下面这个指令：

location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

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

应当被解释为下面这些指令：

variable $forbidden
check against zero
    return 403
    end of code
variable $slow
check against zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code

注意到：上面这段没有 limit_rate指令相关的命令，因为它与ngx_http_rewrite_module模块无关。

if 块中建立了单独的配置，如果条件为真，当 limit_rate 等于 10K 的时候，请求会被分配给这段配置。

指令如下：

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

可以让上面这段命令变得更短些：

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

相对应的指令看起来就像这样：

match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code