Mastering Nginx location: Syntax, Matching Rules, and Best Practices

Nginx Series Introduction

We continue exploring the third part of the Nginx main configuration file, focusing on the http block's location directive.

1. Introduction to location

The location block directive matches URL requests and determines how each request is processed; understanding the matching order of multiple locations is essential.

2. location Syntax

Two matching rules exist:

Standard URL matching with optional parameters: location [ = | ~ | ~* | ^~ ] uri { … } Named locations using @, similar to a goto statement:

location @name { … }

location Matching Parameters Explained

(1) = – exact match; the request URI must be identical.

location = /abc/ {
  ...
}
# matches http://abc.com/abc only
# does not match http://abc.com/abc/index

(2) ~ – case‑sensitive regular expression match.

location ~ /Abc/ {
  ...
}
# matches http://abc.com/Abc/ only

(3) ~* – case‑insensitive regular expression match.

location ~* /Abc/ {
  ...
}
# matches both http://abc.com/Abc/ and http://abc.com/abc/

(4) ^~ – prefix match that stops further regex evaluation.

location ^~ /index/ {
  ...
}
# matches any request starting with /index/

(5) No parameter – default case‑sensitive prefix match (equivalent to ~ + ^~).

location /index/ {
  ...
}
# matches /index, /index/index.page, etc.

(6) @ – internal redirect.

location /index/ {
  error_page 404 @index_error;
}
location @index_error {
  ...
}
# redirects 404 errors to the named location

3. location Matching Order

The precedence is: = > ^~ > ~ | ~* > longest prefix match >

/

Priority (lower number = higher priority)

location = # exact match

location ^~ # prefix with parameter

location ~ # regex (case‑sensitive)

location ~* # regex (case‑insensitive)

location /a # ordinary prefix match

location / # catch‑all

Example

location = /  { # A }
location = /login { # B }
location ^~ /static/ { # C }
location ~ \.(gif|jpg|png|js|css)$ { # D }
location ~* \.png$ { # E }
location !~ \.xhtml$ { # F }
location !~* \.xhtml$ { # G }
location / { # H }

Matching results:

/ → A
/login → B, /register → H
/static/a.html → C
/b.jpg → D (higher priority than E)
/static/c.png → C
/a.PNG → E (case‑insensitive)
/a.xhtml → no match (F and G are exclusions)
/qll/id/1111 → H

4. Trailing Slash in location URI

If the URI is like https://domain.com/, the presence or absence of the trailing slash does not cause a redirect because browsers automatically add it.

If the URI is like https://domain.com/some-dir/, omitting the trailing slash triggers a redirect, as a trailing slash denotes a directory while its absence denotes a file.

Example configuration:

server {
    listen 9001;
    server_name www.abc.com;
    location ~ /edu {
        proxy_pass http://127.0.0.1:8080;
    }
}

Requesting www.abc.com:9001/edu initially looks for a file named edu; not finding it, Nginx treats it as a directory and redirects to /edu/.

Accessing /edu first searches for a file; if absent, it is considered a directory and redirected to /edu/ .

To handle both /doc and /doc/ differently, define separate locations:

location /doc {
    proxy_pass http://www.doc123.com;
}
location /doc/ {
    proxy_pass http://www.doc456.com;
}

Conclusion

If you found this guide helpful, consider clicking “Like” or sharing it – your support motivates further sharing.