ngx_http_rewrite_module

ngx_http_rewrite_module模块

• 指令

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

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

• 在服务器级指定的该模块的指令是按顺序执行的;

指令

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

如果在位置内指定了指令，则在该位置继续处理请求。

例：

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

指定condition的评估。如果为true，则在花括号内指定的模块指令被执行，并且该请求被分配if指令内的配置。if指令内的配置从先前的配置级别继承。

条件可能是以下任何一种情况：

• 变量名称; 如果变量的值是空字符串或“ 0”，则为false ; 在版本1.0.1之前，任何以“ 0” 开头的字符串都被认为是错误的值。

例子：

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指令设置。

停止处理并将指定的内容返回code给客户端。非标准代码444在不发送响应报头的情况下关闭连接。

从版本0.8.42开始，可以指定重定向URL（对于代码301,302,303,307和308）或响应主体text（对于其他代码）。响应正文文本和重定向URL可以包含变量。作为特殊情况，可以将重定向URL指定为此服务器本地的URI，在这种情况下，完整重定向URL根据请求方案（$scheme）和server_name_in_redirect和port_in_redirect指令形成。

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

在版本0.7.51之前仅可以返回以下代码：204,400,402-406,408,410,411,413,416和500-504。代码307不被视为重定向直到版本1.1.16和1.0.13。代码308在版本1.13.0之前不被视为重定向。

另请参阅error_page指令。

如果指定的正则表达式与请求URI匹配，则URI将按replacement字符串中指定的方式更改。这些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;

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

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

value为指定的设置一个variable。该value可以包含文本，变量，他们的组合。

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

内部实施

该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