模块 ngx_http_rewrite_module

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

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

• 在服务器级别 指定的该模块的指令 按顺序执行；
• 反复：
  • 根据请求 URI 搜索 位置 ；
  • 找到的位置内指定的该模块的指令将按顺序执行；
  • 如果请求 URI 被重写， 则重复循环，但不超过 10 次。

停止处理当前的指令集 ngx_http_rewrite_module。

如果在location 内指定了指令 ，则在此位置继续进一步处理请求。

例子：

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

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

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

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

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

• =使用“ ”和“ ”运算 符将变量与字符串进行比较!=；
• 使用“ ~”（区分大小写的匹配）和“ ~*”（不区分大小写的匹配）运算符将变量与正则表达式进行匹配。正则表达式可以包含可供以后在body..变量中重用的捕获。负运算符“ !~”和“ !~*”也可用。如果正则表达式包含“ }”或“ ;”字符，则整个表达式应括在单引号或双引号中。
• -f使用“ ”和“ !-f”运算符 检查文件是否存在；
• -d使用“ ”和“ ”运算符 检查目录是否存在!-d；
• -e使用“ ”和“ ”运算符 检查文件、目录或符号链接是否存在!-e；
• -x使用“ ”和“ ”运算符 检查可执行文件!-x。

例子：

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

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

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，在这种情况下，完整的重定向 URL 是根据请求方案 ( )$scheme以及 server_name_in_redirect和 port_in_redirect指令形成的。

此外，URL可以将带有代码 302 的临时重定向指定为唯一参数。此类参数应以“ http://”、“ https://”或“ $scheme”字符串开头。AURL可以包含变量。

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

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

last

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

break

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

redirect

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

permanent

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

完整的重定向 URL 是根据请求方案 ( $scheme) 以及 server_name_in_redirect和 port_in_redirect指令形成的。

例子：

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

但如果这些指令放在“ /download/”位置，则该last标志应替换为 break，否则 nginx 将循环 10 次并返回 500 错误：

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

如果replacement字符串包含新的请求参数，则先前的请求参数将附加在它们后面。如果不希望出现这种情况，请在替换字符串末尾放置问号以避免附加它们，例如：

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

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

rewrite_log off;

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

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

uninitialized_variable_warn on;

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

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

例如，指令

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

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /body/mp3/.mp3 break;
}

将被翻译成这些指令：

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

请注意，上面没有关于 limit_rate 指令的说明，因为它与模块无关 ngx_http_rewrite_module。为if块创建单独的配置。如果条件成立，则为请求分配此配置，其中limit_rate等于 10k。

该指令

rewrite ^/(download/.*)/media/(.*)\..*$ /body/mp3/.mp3 break;

如果正则表达式中的第一个斜杠放在括号内，则可以将其缩小一个指令：

rewrite ^(/download/.*)/media/(.*)\..*$ body/mp3/.mp3 break;

相应的指令将如下所示：

match of regular expression
copy body
copy "/mp3/"
copy 
copy ".mp3"
end of regular expression
end of code