Module ngx_http_rewrite_module

• Directives
  • break
  • if
  • return
  • rewrite
  • rewrite_log
  • set
  • uninitialized_variable_warn
• Internal Implementation
  

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

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

• 在server级别上指定的该模块的指令按顺序执行；

• repeatedly:

• 根据请求 URI 搜索location；

  • 在找到的位置内指定的该模块的指令按顺序执行；

  • 如果请求 URI 为rewritten，但不超过10 times，则重复循环。

Directives

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

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

如果在location内指定了指令，则将在此位置 continue 处理请求。

Example:

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

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

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

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

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

• 使用“ =”和“ !=”运算符将变量与字符串进行比较；

• 使用“ ~”(用于区分大小写的匹配)和“ ~*”(用于区分大小写的匹配)运算符将变量与正则表达式进行匹配。正则表达式可以包含捕获，以后可在$1 .. $9变量中使用这些捕获。负运算符“ !~”和“ !~*”也可用。如果正则表达式包含“ }”或“ ;”字符，则整个表达式应用单引号或双引号引起来。

• 使用“ -f”和“ !-f”运算符检查文件是否存在；

• 使用“ -d”和“ !-d”运算符检查目录是否存在；

• 使用“ -e”和“ !-e”运算符检查文件，目录或符号链接是否存在；

• 使用“ -x”和“ !-x”运算符检查可执行文件。

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;
}

Syntax:	return code [text];
return code URL; return URL;
默认值：	—
上下文： server，location，if

停止处理并将指定的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可以包含变量。

另请参见error_page指令。

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

如果指定的正则表达式与请求 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指令形成的。

Example:

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;

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

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

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

Syntax:	set $variable value;
Default:	—
Context:	server , location , if

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

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

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

Internal Implementation

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。

The directive

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