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.
位置可以由前缀字符串或正则表达式定义。正则表达式使用前面的“*”修饰符(用于不区分大小写的匹配)或“”修饰符(用于区分大小写的匹配)指定。为了找到与给定请求匹配的位置,nginx 首先检查使用前缀字符串(前缀位置)定义的位置。其中,选择并记住匹配前缀最长的位置。然后按照它们在配置文件中出现的顺序检查正则表达式。正则表达式的搜索在第一次匹配时终止,并使用相应的配置。如果找不到与正则表达式的匹配项,则使用之前记住的前缀位置的配置。
location blocks can be nested, with some exceptions mentioned below.
位置块可以嵌套,下面提到了一些例外。
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.
如果最长匹配前缀位置具有“^~”修饰符,则不检查正则表达式。
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 = /”将加速这些请求的处理,因为搜索在第一次比较后立即终止。这样的位置显然不能包含嵌套位置。
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 的版本中,如果请求匹配没有“=”和“^~”修饰符的前缀位置,搜索也会终止并且不检查正则表达式。
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,“/images/1.gif”请求将匹配配置D,“/documents/1.jpg”请求将匹配配置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.
“@”前缀定义了一个命名位置。这样的位置不用于常规请求处理,而是用于请求重定向。它们不能嵌套,也不能包含嵌套位置。
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:
如果位置由以斜杠字符结尾的前缀字符串定义,并且请求由 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 或 grpc_pass 之一处理,则执行特殊处理。响应具有等于此字符串但没有尾部斜杠的 URI 的请求,带有代码 301 的永久重定向将返回到附加斜杠的请求的 URI。如果不需要,可以像这样定义 URI 和位置的精确匹配:
location /user/ {
proxy_pass http://user.example.com;
}
location = /user {
proxy_pass http://login.example.com;
}