Master Nginx Regex and Location Matching: Rules, Priorities, and Examples

In this article the author demonstrates Nginx v1.23.2 on a single‑node environment, focusing on regular expressions, location path matching rules, and their priority.

1. Nginx Regular Expressions

Nginx follows standard regular expression syntax, with the special characters indicating the start of a regex. Regular expressions can be used in server blocks or within location directives.

Common regex symbols

^   – match start of string
$   – match end of string
.   – match any single character except newline (use [.
] for any character)
\d – match digits
\w – match letters, digits, underscore or Chinese characters
\s – match whitespace
\b – match word boundary
*   – match preceding token zero or more times
+   – match preceding token one or more times
?   – match preceding token zero or one time (equivalent to {0,1})
{n} – repeat exactly n times
{n,} – repeat n or more times
{n,m} – repeat between n and m times
[]  – character class, e.g., [a-z]
()  – group, e.g., (jpg|gif|swf)
|   – alternation
!   – negation (applies to the following expression)
\   – escape character

2. Location Path Matching Rules and Priority

The location directive defines how Nginx matches request URIs. Matching proceeds in several steps:

Exact match using the = prefix stops further search.

All non‑regex locations (including those with ^~) are examined; the longest matching prefix is remembered.

If the remembered prefix uses ^~, that location is selected and the search stops.

Regular‑expression locations ( ~ and ~*) are evaluated in the order they appear; the first match is used.

If no regex matched, the previously remembered longest prefix is used.

Official priority order (simplified):

1. = exact match
2. Longest literal prefix (if ^~ then stop)
3. Regular expressions in definition order
4. Fallback to longest literal prefix

The five main location prefixes are: = uri – exact match ~ regex – case‑sensitive regex ~* regex – case‑insensitive regex ^~ uri – prefix match that disables further regex checks uri – plain prefix match without any prefix

Priority among these types is = > ^~ > ~* > ~ > plain prefix > /.

Examples

1. No prefix (plain prefix)

server {
    listen 8081;
    server_name 127.0.0.1;
    location /aaa {
        default_type text/plain;
        return 200 "access success aaa 
\r";
    }
}

This matches /aaa, /aaa/, /aaadef, etc., but not /Aaa (case‑sensitive).

2. Exact match with =

server {
    listen 8081;
    server_name 127.0.0.1;
    location = /bbb {
        default_type text/plain;
        return 200 "access success bbb 
\r";
    }
}

Matches only /bbb (and query strings), not /bbb/ or different case.

3. Case‑sensitive regex ~

server {
    listen 8081;
    server_name 127.0.0.1;
    location ~^/eee\w$ {
        default_type text/plain;
        return 200 "access success. 000 Regular expression matched: eee  
\r";
    }
}

Matches URIs like /eeeb, /eeeB, /eee2 but not /eee or upper‑case variants.

4. Case‑insensitive regex ~*

server {
    listen 8081;
    server_name 127.0.0.1;
    location ~*^/ddd\w$ {
        default_type text/plain;
        return 200 "access success. 111 Regular expression matched: ddd  
\r";
    }
}

Matches /dddb, /dddB, /DddH, etc., regardless of case.

5. Prefix with ^~ (non‑regex, higher priority)

server {
    listen 8081;
    server_name 127.0.0.1;
    location ^~ /fff {
        default_type text/plain;
        return 200 "access success. Non Regular expression matched: fff  
\r";
    }
}

Matches any URI starting with /fff and stops further searching.

Named location

Using @ defines an internal named location, useful for error handling or internal redirects.

# Example: redirect 404 errors internally
error_page 404 = @fetch;
location @fetch {
    proxy_pass http://fetch;
}

Typical error pages can also be defined with regular locations.

Visual flowcharts illustrating the matching process are shown in the original article (images omitted here).