FAQ

Page Discussion Edit History

ChsHttpRewriteModule

Contents

ngx_http_rewrite_module

This module makes it possible to change URI using regular expressions, and to redirect and select configuration depending on variables.

璇ユā鍧楀厑璁镐娇鐢ㄦ鍒欒〃杈惧紡鏀瑰彉URI锛屽苟涓旀牴鎹彉閲忔潵杞悜浠ュ強閫夋嫨閰嶇疆銆

If the directives of this module are given at the server level, then they are carried out before the location of the request is determined. If in that selected location there are further rewrite directives, then they also are carried out. If the URI changed as a result of the execution of directives inside location, then location is again determined for the new URI.

濡傛灉鍦╯erver绾у埆璁剧疆璇ラ夐」锛岄偅涔堜粬浠皢鍦╨ocation涔嬪墠鐢熸晥銆傚鏋滃湪location杩樻湁鏇磋繘涓姝ョ殑閲嶅啓瑙勫垯锛宭ocation閮ㄥ垎鐨勮鍒欎緷鐒朵細琚墽琛屻傚鏋滆繖涓猆RI閲嶅啓鏄洜涓簂ocation閮ㄥ垎鐨勮鍒欓犳垚鐨勶紝閭d箞location閮ㄥ垎浼氬啀娆¤鎵ц浣滀负鏂扮殑URI銆

This cycle can be repeated up to 10 times, after which Nginx returns a 500 error.

杩欎釜寰幆浼氭墽琛10娆★紝鐒跺悗Nginx浼氳繑鍥炰竴涓500閿欒銆

Directives

  • [#break break]
  • [#if if]
  • [#return return]
  • [#rewrite rewrite]
  • [#set set]
  • [#uninitialized_variable_warn uninitialized_variable_warn]

Template:Anchor

break

璇硶: break

榛樿鍊: none

浣滅敤鍩: server, location, if

Completes the current set of rules. 浣滅敤鏄畬鎴愬綋鍓嶇殑瑙勫垯鍒

绀轰緥:

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

Template:Anchor

if

璇硶: if (condition) { ... }

榛樿: none

浣滅敤鍩: server, location

Checks the truth of a condition. If the condition evaluates to true, then the code indicated in the curly braces is carried out and the request is processed in accordance with the configuration within the following block. Configuration inside directive if is inherited from the previous level.

They can be assigned as the condition: 鏉′欢璇彞鍙互浣夸笅鍒楃殑鍑犵锛

  • the name of variable; false values are: empty string "", or any string starting with "0";
 涓涓彉閲忕殑鍚嶇О锛涘鏋滃彉閲忕殑鍊间负绌哄瓧绗︿覆""鎴栬呬换浣曚互0寮濮嬬殑瀛楃涓诧紝鍒欒〃绀烘潯浠惰鍙ョ殑鍊间负鍋
  • the comparison of variable with the line with using the = and != operators;
  • pattern matching with regular expressions using the symbols ~* and ~:
  1. 姝e垯琛ㄨ揪寮忓舰寮忕殑妯″紡鍖归厤锛屽~*鍜寏
  • ~ is case-sensitive match;
  • 鈥榽鈥欒〃绀哄ぇ灏忓啓鏁忔劅鐨勫尮閰
  • ~* specifies a case-insensitive match (firefox matches FireFox)
  • 鈥榽*鈥欒〃绀哄ぇ灏忓啓涓嶆晱鎰熺殑鍖归厤锛堜緥濡傦細鈥渇irefox鈥濆瓧绗︿覆鍙互鎴愬姛鍖归厤鈥淔ireFox鈥濓級
  • !~ and !~* mean the opposite, "doesn't match"
  •  !~鍜!~*浠h〃璺熷悗闈㈢殑姝e垯鍖归厤瑙勫垯鐩稿弽鐨勮鍒欙紝琛ㄧず涓嶈兘鍖归厤褰撳墠姝e垯琛ㄨ揪寮忚鍒欑殑瀛楃涓叉墽琛屽悗闈㈢殑澶勭悊璇彞
  • checking for the existence of a file using the -f and !-f operators;浣跨敤-f鍙傛暟浠ュ強!-f鍙傛暟妫娴嬩竴涓枃浠舵槸鍚﹀瓨鍦
  • checking existence of a directory using the -d and !-d operators;浣跨敤-d鍙傛暟浠ュ強!-d鍙傛暟妫娴嬩竴涓洰褰曪紙璺緞锛夋槸鍚﹀瓨鍦
  • checking existence of a file, directory or symbolic link using the -e and !-e operators;

浣跨敤-e浠ュ強!-e妫娴嬫槸鍚﹀瓨鍦ㄤ竴涓枃浠讹紝涓涓洰褰曟垨鑰呬竴涓鍙烽摼鎺ャ

  • checking whether a file is executable using the -x and !-x operators.浣跨敤-x浠ュ強!-x妫娴嬩竴涓枃浠舵槸鍚﹀彲鎵ц


Parts of the regular expressions can be in parentheses, whose value can then later be accessed in the $1 to $9 variables.

姝e垯琛ㄨ揪寮忛儴鍒嗗彲浠ュ祵濂楋紝琛ㄨ揪寮忓悗闈㈢殑閮ㄥ垎濡傛灉鐢ㄥ埌鍓嶉潰鐨勮〃杈惧紡鍙互鐢 $1 鍒$9 鍙橀噺琛ㄧず銆

Examples of use: 渚嬪瓙濡備笅锛

if ($http_user_agent ~ MSIE) {
: rewrite  ^(.*)$  /msie/$1  break;
}
if ($http_cookie ~* "id=([^;] +)(?:;|$)" ) {
: set  $id  $1;
}
if ($request_method = POST ) {
: return 405;
}
if (!-f $request_filename) {
: break;
: proxy_pass  http://127.0.0.1;
}
if ($slow) {
: limit_rate  10k;
}
if ($invalid_referer) {
: return   403;
}

The value of the built-in variable $invalid_referer is given by the directive valid_referers.

Template:Anchor

return

璇硶: return code

榛樿鍊: none

浣滅敤鍩: server, location, if

This directive concludes execution of the rules and returns the status code indicated to client. It is possible to use the following values: 204, 400, 402-406, 408, 410, 411, 413, 416 and 500-504. Furthermore, nonstandard code 444 closes the connection without sending any headers.

杩欎釜鎸囦护鏍规嵁瑙勫垯鐨勬墽琛屾儏鍐碉紝杩斿洖涓涓姸鎬佸肩粰瀹㈡埛绔傚彲浣跨敤鍊煎寘鎷細204锛400锛402-406锛408锛410锛411锛413锛416浠ュ強500-504銆備篃鍙互鍙戦侀潪鏍囧噯鐨444浠g爜-鏈彂閫佷换浣曞ご淇℃伅涓嬬粨鏉熻繛鎺ャ

Template:Anchor

rewrite

璇硶: rewrite regex replacement flag

榛樿: none

浣滅敤鍩: server, location, if

This directive changes URI in accordance with the regular expression and the replacement string. Directives are carried out in order of appearance in the configuration file.

杩欎釜鎸囦护鏍规嵁姝e垯琛ㄨ揪寮忔垨鑰呭緟鏇挎崲鐨勫瓧绗︿覆鏉ユ洿鏀筓RI銆傛寚浠ゆ牴鎹厤缃枃浠朵腑鐨勫厛鍚庨『搴忔墽琛岀敓鏁堛

Be aware that the rewrite regex only matches the relative path instead of the absolute URL. If you want to match the hostname, you should use an if condition, like so:

娉ㄦ剰锛氶噸鍐欒鍒欏彧鍖归厤鐩稿璺緞锛堜笉鍖呮嫭缁濆鐨刄RL锛夈傚鏋滀綘鎯抽厤瀵逛富鏈哄悕锛屼綘搴旇浣跨敤if璇彞锛屽涓嬶細

if ($host ~* www\.(.*)) {
: set $host_without_www $1;
: rewrite ^(.*)$ http://$host_without_www$1 permanent; # $1 contains '/foo', not 'www.mydomain.com/foo'
}

Flags make it possible to end the execution of rewrite directives. flag鏍囪鍙互鍋滄閲嶅畾鍚戣鍒欑殑鎵ц

If the replacement string begins with http:// then the client will be redirected, and any further rewrite directives are terminated. 濡傛灉鏇挎崲瀛楃涓蹭互鈥渉ttp:鈥濆紑濮嬶紝瀹㈡埛绔細琚噸瀹氬悜锛岃屼笖鍏朵粬鐨勯噸瀹氬悜瑙勫垯閮戒細琚粓姝€

Flags can be any of the following: 鍙敤鐨刦lag鏍囪鏈夛細

  • last - completes processing of rewrite directives, after which searches for corresponding URI and location
 瀹屾垚璇ewrite瑙勫垯鐨勬墽琛岋紝涔嬪悗鏌ユ壘绗﹀悎鐨刄RI鍜宭ocation
  • break - completes processing of rewrite directives
 缁堟鍖归厤锛屼笉鍐嶅尮閰嶅悗闈㈢殑瑙勫垯
  • redirect - returns temporary redirect with code 302; it is used if the substituting line begins with http://
 杩斿洖302涓存椂閲嶅畾鍚戯紝褰撴浛浠h浠ttp:寮濮嬫椂鍙互浣跨敤锛屽湴鍧鏍忎細鏄剧ず璺宠浆鍚庣殑鍦板潃
  • permanent - returns permanent redirect with code 301
 杩斿洖301姘镐箙閲嶅畾鍚

Note that if an redirect is relative (has no host part), then when redirecting Nginx uses the "Host" header if the header match name of server_name directive or the first name of server_name directive, if the header does not match or is absent. If no server_name is set, then the local hostname is used. If you want Nginx to always use the "Host" header, you can use a wildcard "*" server_name (but see the restrictions on doing so).Example:


rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  last;
rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   last;
return   403;

But if we place these directives in location /download/, then it is necessary to replace flag "last" by "break", otherwise nginx will hit the 10 cycle limit and return error 500:

  1. 濡傛灉鎴戜滑灏嗗綋鍓嶇殑鍖归厤瑙勫垯浣跨敤鍦/download/鐩綍涓嬶紝灏辫灏"last"鏇挎崲涓"break"浜嗐傚惁鍒檔ginx灏变細杈惧埌10娆″惊鐜殑涓婇檺锛岀劧鍚庤繑鍥炰釜500閿欒
location /download/ {
: rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;
: rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   break;
: return   403;
}

If in the line of replacement arguments are indicated, then the rest of the request arguments are appended to them. To avoid having them appended, place a question mark as the last character:

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

娉: 瀵硅姳鎷彿( { 鍜 } )鏉ヨ, 浠栦滑鏃㈣兘鐢ㄥ湪閲嶅畾鍚戠殑姝e垯琛ㄨ揪寮忛噷锛屼篃鏄敤鍦ㄩ厤缃枃浠堕噷鍒嗗壊浠g爜鍧, 涓轰簡閬垮厤鍐茬獊, 姝e垯琛ㄨ揪寮忛噷甯﹁姳鎷彿鐨勮瘽锛屽簲璇ョ敤鍙屽紩鍙凤紙鎴栬呭崟寮曞彿锛夊寘鍥淬傛瘮濡傦紝瑕佸皢绫讳技浠ヤ笅鐨剈rl

 
/photos/123456 

閲嶅畾鍚戝埌锛

 
/path/to/photos/12/1234/123456.png 

鍙互鐢ㄤ互涓嬫柟娉 (娉ㄦ剰鍙屽紩鍙):

rewrite  "/photos/([0-9] {2})([0-9] {2})([0-9] {2})" /path/to/photos/$1/$1$2/$1$2$3.png; 

Template:Anchor

set

syntax: set variable value

default: none

context: server, location, if

Directive establishes value for the variable indicated. As the value it is possible to use a text, variables and their combination.

Template:Anchor

uninitialized_variable_warn

syntax: uninitialized_variable_warn on|off

default: uninitialized_variable_warn on

context: http, server, location, if

Enables or disables logging of warnings about noninitialized variables.

Internally, the rewrite directives are compiled at the time the configuration file is loaded into internal codes, usable during the request by the interpreter.

This interpreter is a simple stack virtual machine. For example, the directive:

location /download/ {
: if ($forbidden) {
: return   403;
: }
: if ($slow) {
: limit_rate  10k;
: }
: rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;
}

will be compiled into this sequence:

: variable $forbidden
: checking to zero
: recovery 403
: completion of entire code
: variable $slow
: checking to zero
: checkings of regular expression
: copying "/"
: copying $1
: copying "/mp3/"
: copying $2
: copying "..mpe"
: completion of regular expression
: completion of entire sequence

Note that there is no code for directive limit_rate, since it does not refer to module ngx_http_rewrite_module. The "if" block exists in the same part of the configuration as the "location" directive.

If $slow is true, then what's inside the "if" block is evaluated, and in this configuration limit_rate it is equal to 10k.

Directive:

: rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;

It is possible to reduce the sequence, if in the regular expression we include the first slash inside the parentheses:

: rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;

then the sequence will appear like this:

: checking regular expression
: copying $1
: copying "/mp3/"
: copying $2
: copying "..mpe"
: completion of regular expression
: completion of entire code

References

Original Documentation