模块 ngx_http_rewrite_module

模块 ngx_http_rewrite_module 用于使用 PCRE 正则表达式更改请求 URI，返回重定向，并有条件地选择配置。

指令 break、if、return、rewrite 和 set 将按以下顺序处理：

• 按顺序执行在 server 级别指定的此模块的指令；
• 重复执行：
  • 基于请求 URI 搜索 location；
  • 按顺序执行在找到的位置内指定的此模块的指令；
  • 如果请求 URI 被 重写，但不超过 10 次，则重复此过程。

停止处理当前一组 ngx_http_rewrite_module 指令。

如果指令位于 location 内，则继续在此位置处理请求。

示例：

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

评估指定的 condition。如果为真，则执行大括号内指定的模块指令，并将请求分配给 if 指令内的配置。 if 指令内的配置从前一个配置级别继承。

条件可以是以下任何一种：

• 一个变量名；如果变量的值是空字符串或“0”，则为false；

  在1.0.1版本之前，任何以“0”开头的字符串都被视为false值。

• 使用“=”和“!=”运算符将变量与字符串进行比较；
• 使用“~”（用于区分大小写的匹配）和“~*”（用于不区分大小写的匹配）运算符将变量与正则表达式进行匹配。正则表达式可以包含捕获，在$1..$9变量中供以后重用。还提供了负运算符“!~”和“!~*”。如果正则表达式包含“}”或“;”字符，则整个表达式应该用单引号或双引号括起来。
• 使用“-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;
}

通过valid_referers指令设置的$invalid_referer内嵌变量的值。

停止处理并将指定的code返回给客户端。非标准代码444会关闭连接而不发送响应头。

从版本0.8.42开始，可以指定重定向URL（用于代码301、302、303、307和308）或响应体text（用于其他代码）。响应体文本和重定向URL可以包含变量。作为特例，重定向URL可以指定为本服务器的URI，此时根据请求方案（$scheme）以及server_name_in_redirect和port_in_redirect指令来形成完整的重定向URL。

此外，可以指定用于代码302临时重定向的URL作为唯一参数。这样的参数应以“http://”、“https://”或“$scheme”字符串开头。一个URL可以包含变量。

在版本0.7.51之前，只能返回以下代码：204、400、402 — 406、408、410、411、413、416和500 — 504。

在版本1.1.16和1.0.13之前，代码307不被视为重定向。

在版本1.13.0之前，代码308不被视为重定向。

还请参阅error_page指令。

如果指定的正则表达式与请求URI匹配，则按照replacement字符串中指定的方式更改URI。 rewrite指令按照它们在配置文件中出现的顺序依次执行。可以使用标志终止指令的进一步处理。如果替换字符串以“http://”、“https://”或“$scheme”开头，则处理将停止，并将重定向返回给客户端。

可选的flag参数可以是以下之一：

last

停止处理当前ngx_http_rewrite_module指令集，并开始搜索匹配更改后URI的新位置；

break

像break指令一样停止处理当前ngx_http_rewrite_module指令集；

redirect

返回302代码的临时重定向；如果替换字符串不以“http://”、“https://”或“$scheme”开头，则使用；

permanent

返回301代码的永久重定向。

完整的重定向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/”位置内，则应将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;
}

如果replacement字符串包含新的请求参数，则将以前的请求参数附加在其后。如果不需要这样做，则在替换字符串末尾加上问号可以避免它们被附加，例如：

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

如果正则表达式包含“}”或“;”字符，则整个表达式应该用单引号或双引号括起来。

rewrite_log off;

启用或禁用ngx_http_rewrite_module模块指令处理结果的记录到error_log，记录级别为notice。

为指定的variable设置一个value。 value可以包含文本、变量及其组合。

uninitialized_variable_warn on;

控制是否记录有关未初始化变量的警告。

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