Mastering Nginx Location Matching: Order, Rules, and Best Practices

Nginx location matching order details

Exact match (=) When the request URI exactly equals the string after location , Nginx selects this block with the highest priority. Example:

location = /favicon.ico {
    # handle favicon.ico request
}

The block is used only for the exact /favicon.ico request.

Longest‑string match (no modifier) If the request URI starts with a prefix defined by a location block, Nginx chooses the block whose prefix is the longest. Example:

location /images/ {
    # handle /images/* requests
}

location /images/jpg/ {
    # handle /images/jpg/* requests
}

For /images/jpg/photo.jpg , the second block wins because its prefix is longer.

Regex match (~ and ~*) Regular‑expression locations allow complex patterns. ~ is case‑sensitive, ~* is case‑insensitive. Nginx checks regex locations in the order they appear and stops at the first match. Example:

location ~ \.(gif|jpg|png)$ {
    # case‑sensitive image extensions
}

location ~* \.(GIF|JPG|PNG)$ {
    # case‑insensitive image extensions
}

Typically place regex locations later in the file to avoid unnecessary matching overhead.

Prefix match (^~) If a URI starts with a given prefix and the prefix is not followed by a slash or other characters, the ^~ block is selected before any regex checks. Example:

location ^~ /static/ {
    # handle /static/* requests (no further regex search)
}

For /static/file.txt this block matches; for /static/subdir/file.txt it matches only if no longer prefix exists. Note that ^~ behaves like a special case of longest‑string matching and may stop the search even if a longer prefix exists.

Default match (/) If no other location block matches, Nginx falls back to the default block, usually location / , placed at the end of the configuration:

location / {
    # handle all remaining requests
}

This serves as a catch‑all fallback.

Summary and best practices

Prefer exact matches and longest‑string matches for static assets to maximize performance.

Use regex locations sparingly, especially on high‑traffic sites, because they incur higher processing cost.

Place the default location / block at the end of the file as a fallback.

Always test configuration changes thoroughly to ensure every request is handled as intended.

Reference: https://www.cnblogs.com/ydswin/p/18090568