NGINX location search order and priority: Explained with examples

Understanding how NGINX resolves requests to specific location blocks is critical for developing secure, efficient, and properly functioning websites. In this guide, we will dive into the intricacies of the NGINX location directive by exploring its search order and priority with relevant examples.

What is the location directive?

The location directive in NGINX is used to define how to process and respond to requests for a specific part of the server. This includes applying specific configuration to certain requests based on the URI that is requested.

Location Syntax

The syntax for the location directive can typically include a modifier, followed by a path like so:

location [modifier] /path/ {
    # Configuration directives
}

Modifiers and Match Types

NGINX uses the following modifiers to match URIs:

• None (Prefix Match): Without a modifier, NGINX applies the longest matching prefix.
• = (Exact Match): NGINX matches the exact URI.
• ~ (Case-Sensitive Regex Match): This performs a case-sensitive regular expression match.
• ~* (Case-Insensitive Regex Match): This performs a case-insensitive regex match.
• ^~ (Prefix Based Match): This tells NGINX to stop searching if this prefix match is found.

NGINX evaluates the location directives in a specific order:

1. Exact match (using =)
2. Regular expressions (using ~ or ~*) in the order they are defined in the configuration
3. Prefix match (using ^~)
4. Longest prefix without a modifier

Let us delve into each match type with examples.

Exact Match

location = /exact {
    # This block will only be chosen if the URI is exactly /exact
}

An exact match is considered the highest priority.

Regular Expression Match

location ~ /documents/(.+\..+) {
    # This block will match any request to /documents with a file extension
}

Prefix Matches

location ^~ /static {
    # This block will match any request starting with /static and halt further searching
}

location /images {
    # This block matches any request starting with /images
}

Best Practices

Here are some best practices when configuring location blocks:

• Use exact matches for static pages that you know won’t change.
• Utilize regular expressions for dynamic URI matching, but be aware of the order of precedence.
• Prefix matches (^~) can be used for performance benefits if you do not need regular expression matches.
• Root-level (/) location should be your fallback option.

Common Pitfalls

Be cautious of certain common issues when configuring location blocks:

• Regular expressions evaluated out of order can lead to unexpected results.
• Overusing regular expressions can degrade performance.
• Prefix directives without the ^~ modifier may be overridden by regular expressions.

Final Words

Through these examples and explanations, you should now have a better understanding of the NGINX location directive’s order and priority. This knowledge will allow you to create refined and more responsive configurations for your web server.