模块 ngx_http_rewrite_module
指令 break if return rewrite rewrite_log set uninitialized_variable_warn 内部实现 |
ngx_http_rewrite_module
模块用于使用 PCRE 正则表达式更改请求 URI、返回重定向和有条件地选择配置。
以下列顺序处理 break、if、return、rewrite 和 set 指令
- 在 server 级别上指定的此模块的指令按顺序执行;
- 重复
指令
语法 |
break; |
---|---|
默认值 | — |
上下文 |
server 、location 、if |
停止处理当前的 ngx_http_rewrite_module
指令集。
如果在 location 内指定了指令,则将继续在此 location 中处理请求。
示例
if ($slow) { limit_rate 10k; break; }
语法 |
if ( |
---|---|
默认值 | — |
上下文 |
server 、location |
评估指定的 条件
。如果为真,则执行大括号内指定的此模块指令,并将配置分配给 if
指令内的请求。if
指令内的配置从上一个配置级别继承。
条件可以是以下任何一项
-
变量名;如果变量的值为空字符串或“
0
”,则为假;在 1.0.1 版本之前,以“
0
”开头的任何字符串都被视为假值。 -
使用“
=
”和“!=
”运算符将变量与字符串进行比较; -
使用“
~
”(用于区分大小写的匹配)和“~*
”(用于不区分大小写的匹配)运算符将变量与正则表达式进行匹配。正则表达式可以包含捕获,这些捕获可供以后在$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; }
$invalid_referer
嵌入式变量的值由 valid_referers 指令设置。
语法 |
return return return |
---|---|
默认值 | — |
上下文 |
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
可以包含变量。
在版本 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 指令。
语法 |
rewrite |
---|---|
默认值 | — |
上下文 |
server 、location 、if |
如果指定的正则表达式与请求 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/(.*)\..*$ $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 |
---|---|
默认值 |
rewrite_log off; |
上下文 |
http 、server 、location 、if |
启用或禁用将ngx_http_rewrite_module
模块指令处理结果记录到error_log中(级别为notice
)。
语法 |
set |
---|---|
默认值 | — |
上下文 |
server 、location 、if |
为指定的variable
设置value
。value
可以包含文本、变量及其组合。
语法 |
uninitialized_variable_warn |
---|---|
默认值 |
uninitialized_variable_warn on; |
上下文 |
http 、server 、location 、if |
控制是否记录有关未初始化变量的警告。
内部实现
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