Mastering Nginx Location Matching Order: Tips and Best Practices

Table of Contents

Nginx location matching order detailed explanation

Summary and best practices

The location matching order is a core concept in Nginx configuration that determines how incoming requests are processed; understanding it helps optimize performance and ensure correct application behavior.

Nginx location matching order detailed explanation

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

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

Only when the URI is exactly /favicon.ico will this block be used.

Longest prefix match (no modifier) If the request URI starts with a location string and that string is the longest among all matches, Nginx selects that block. Example:

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

For the request /images/jpg/photo.jpg , the second block matches because it has a longer prefix.

Regex match (~ and ~*) ~ denotes case‑sensitive regex, while ~* denotes case‑insensitive regex. Nginx checks regex locations in the order they appear and stops at the first match. Example:

location ~ \.(gif|jpg|png)$ {
    # handle .gif, .jpg, .png (case‑sensitive)
}
location ~* \.(GIF|JPG|PNG)$ {
    # handle .GIF, .JPG, .PNG (case‑insensitive)
}

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

Prefix match (^~) If a URI starts with a string and the location is marked ^~ , Nginx selects it before evaluating any regex locations. Example:

location ^~ /static/ {
    # handle requests starting with /static/ (no further regex checks)
}

For /static/file.txt this block matches; deeper sub‑directories may not match unless no longer prefix exists.

Default match (/) If no other location matches, Nginx uses the default location / block, usually placed at the end as a catch‑all.

location / {
    # handle all other requests
}

Summary and Best Practices

Prefer exact and longest‑prefix matches for static resources to improve performance.

Use regex locations sparingly, especially on high‑traffic sites, due to higher matching cost.

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

Thoroughly test configuration changes to ensure requests are handled correctly.

Following these practices helps keep Nginx efficient and reliable.

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