Nginx Location詳細總結

上一篇文章咱們用echo模塊作了試驗，此次咱們來看看官方文檔，這是地址: http://nginx.org/en/docs/http/ngx_http_core_module.html#location , 我嘗試着翻譯以下。

正文

Syntax: 語法	location [ = | ~ | ~* | ^~ ] uri { ... } location @name { ... }
Default: 默認	—
Context: 使用場景/語境	server, location

Sets configuration depending on a request URI. 基於請求uri的配置規則

The matching is performed against a normalized URI, after decoding the text encoded in the 「%XX」 form, resolving references to relative path components 「.」 and 「..」, and possible compression of two or more adjacent slashes into a single slash. 匹配針對從"%xx"格式的文本解碼以後的正常的uri生效，解析相對路徑引用 "." 和 ".."，以及將兩個或更多的相鄰的斜槓壓縮成單斜槓。

A location can either be defined by a prefix string, or by a regular expression. Regular expressions are specified with the preceding 「~*」 modifier (for case-insensitive matching), or the 「~」 modifier (for case-sensitive matching). To find location matching a given request, nginx first checks locations defined using the prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered. Then regular expressions are checked, in the order of their appearance in the configuration file. The search of regular expressions terminates on the first match, and the corresponding configuration is used. If no match with a regular expression is found then the configuration of the prefix location remembered earlier is used.

Location 能夠用前綴字符串定義，或者正則表達式。正則表達式前面帶有 ~* 修飾 (大小寫不敏感匹配) ，或者 ~ 修飾 （大小寫敏感匹配）. 爲了找到和一個給定的請求相匹配的location，nginx 首先檢查 帶了前綴字符串的location(也叫前綴location). 在它們當中，擁有最長的匹配前綴的location將被選中並被記錄下來。而後按照在配置文件中的前後順序，依次檢查正則表達式。正則表達式的搜索會在第一個匹配的時候終止，而後相應的配置將被使用。若是沒有命中正則表達式，則會使用以前被記錄下來的前綴location。

location blocks can be nested, with some exceptions mentioned below.

location 模塊能夠被嵌套，如下是一些例外狀況:

For case-insensitive operating systems such as macOS and Cygwin, matching with prefix strings ignores a case (0.7.7). However, comparison is limited to one-byte locales. 對於大小寫不敏感的操做系統，例如macOS和Cygwin，匹配前綴字符串會忽略一個大寫(0.7.7版本). 然而，比較被限制在單字節的地方。

Regular expressions can contain captures (0.7.40) that can later be used in other directives. 正則表達式能夠包含匹配，這些匹配能夠在後續其餘指令中被用到的。(0.7.40版本)

If the longest matching prefix location has the 「^~」 modifier then regular expressions are not checked. 若是最長的匹配到的前綴location帶有 ^~ 修飾符，那麼正則表達式將不會被檢查。

Also, using the 「=」 modifier it is possible to define an exact match of URI and location. If an exact match is found, the search terminates. For example, if a 「/」 request happens frequently, defining 「location = /」 will speed up the processing of these requests, as search terminates right after the first comparison. Such a location cannot obviously contain nested locations.

同時，使用 '=' 修飾符可能定義一個精準匹配的uri和location. 若是找到了一個精準匹配，那麼查詢就會終止。例如，若是一個 '/' 請求常常出現，那麼定義 'location = /' 將加快處理這些請求的速度，由於搜索會在第一次比較以後就結束。這種location很顯然不能包含嵌套的location.

In versions from 0.7.1 to 0.8.41, if a request matched the prefix location without the 「 =」 and 「 ^~」 modifiers, the search also terminated and regular expressions were not checked.

在 0.7.1 到 0.8.41 的版本中，若是一個請求命中了 不含有 '=' 或 '^~' 修飾符的前綴location，搜索也會終止，且正則表達式不會被檢查到。

Let’s illustrate the above by an example: 讓咱們用一個例子來展現以上的內容:

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

The 「/」 request will match configuration A, the 「/index.html」 request will match configuration B, the 「/documents/document.html」 request will match configuration C, the 「/images/1.gif」 request will match configuration D, and the 「/documents/1.jpg」 request will match configuration E.

'/' 請求將會匹配到 配置A (精準匹配)

'/index.html' 請求將匹配到 配置B （沒有命中精準匹配，沒有命中前綴匹配，也沒有命中正則匹配，最後命中默認匹配）

'/documents/document.html' 請求將命中 配置C （沒有命中精準匹配，命中了前綴匹配 /documents/，繼續查找正則匹配，沒有命中，使用前綴匹配）

'/images/1.gif' 請求將命中 配置D (沒有命中精準匹配，命中了前綴匹配 ^~ /images/，這個匹配帶了 ^~修飾符，不查找正則匹配，直接使用該前綴匹配)

'/documents/1.jpg' 請求將命中 配置E  (沒有命中精準匹配，同時命中了 /documents 和 ~* \.(gif|jpg|jpeg)$，後面這個最長，被記錄下來，繼續查找正則匹配，沒有命中，使用以前記錄下的最長的前綴匹配，配置E。

The 「@」 prefix defines a named location. Such a location is not used for a regular request processing, but instead used for request redirection. They cannot be nested, and cannot contain nested locations.

'@' 前綴至關於給一個location命了名. 這種location不會用來處理常規的請求，可是會用來請求重定向。它們不能夠被嵌套，也不能夠包含嵌套location.

If a location is defined by a prefix string that ends with the slash character, and requests are processed by one of proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass, or grpc_pass, then the special processing is performed. In response to a request with URI equal to this string, but without the trailing slash, a permanent redirect with the code 301 will be returned to the requested URI with the slash appended. If this is not desired, an exact match of the URI and location could be defined like this:

若是一個location用一個前綴字符串，並以一個斜槓\結束，且這些請求被 proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass 或者 grpc_pass中的一個處理，那麼特殊的處理將被執行。在響應 帶有和這個字符串相等，但沒有最後的斜槓\ 的uri的請求時，會返回一個帶有301狀態碼的永久重定向 給請求的uri，並帶上最後的斜槓\。若是不但願這樣，能夠對uri的精準匹配以及location定義以下: (這樣就不會跳轉301了)

location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}

總結

1, 語法

                修飾符(modifier)         
location  [ = | ~ | ~* | ^~ ]    uri    { ... } 

2, 分類

根據不一樣的修飾符能夠分爲兩大類
2.1 前綴location (prefix location)
2.1.1 無修飾符的普通location，例如 location /abc, location /abc/
2.1.2 帶=的精準匹配location，例如 location =/abc
2.1.3 帶^~表示以某個常規字符串開頭的，非正則表達式location，例如 location ^~ /abc

2.2 正則表達式location (regular expressions location)
2.2.1 ~   區分大小寫的正則location
2.2.2 ~*  不區分大小寫的正則location

3, 匹配規則

3.1 nginx會首先檢查 前綴location

3.1.1 若是命中，擁有最長的匹配字符串的location將被選中並被記錄下來。

3.1.1.1 若是最長前綴匹配location的修飾符是^~時，就不會檢查正則location了，直接選擇該location爲最終location。若是不是，則進入下一步正則匹配。

3.1.2 若是沒有命中，則進入下一步正則匹配。

3.2 若是存在正則location時，按照配置的前後順序(重要!)依次匹配URI。

3.2.1 若是找到匹配的正則location就再也不繼續往下，並選擇該location做爲最終的結果。

3.2.2 若是沒有找到匹配的正則location，則會使用以前被記錄下來的前綴location (若是有的話)。

3.3 若是存在精準匹配location，且請求的uri跟其徹底匹配，選擇該精準匹配location做爲最終的location。

4, 優先級

精準匹配 > ^~修飾符最長前綴匹配 > 正則匹配 > 無修飾符普通最長前綴匹配 > 通用匹配 /

5, 其餘

注意，在同一個Server中，不能同時存在帶有相同字符串的 ^~ 修飾符前綴location 和 無修飾符普通前綴location，以下

server {
        listen 80;
        server_name www.test1.com;
        root /opt/wwwroot/test;

        location /fullpath {
                echo 'prefix fullpath with no modifier';
        }

        location ^~ /fullpath {
                echo 'prefix fullpath with ^~ modifier';
        }
}

若是這兩個同時打開，在 nginx -t 命令檢查nginx 配置時，會報 emerg 級別錯誤

2019/11/05 14:01:52 [emerg] 22355#22355: duplicate location "/fullpath" in /etc/nginx/sites-enabled/default:165

可是，將第二個location 改成 ^~ /fullpath/ 就OK了。