How does Nginx's location directive match? What is the priority?

How does Nginx's location directive match? What is the priority?

Nginx's location directive is used to match request URIs and define how to handle these requests. Understanding the matching rules and priority of location is crucial for correctly configuring Nginx.

Location Matching Rules:

1. Exact Match (=)

Use = for exact matching. If the match is successful, stop searching immediately and use that location.

nginx
location = /exact {
    # Exact match /exact
}

2. Prefix Match (No Modifier)

No modifier is used, matching by prefix. If the match is successful, continue searching for more precise matches.

nginx
location /prefix {
    # Matches URIs starting with /prefix
}

3. Regex Match (~ and ~*)

• ~: Case-sensitive regex match
• ~*: Case-insensitive regex match

nginx
location ~ \.php$ {
    # Matches URIs ending with .php (case-sensitive)
}

location ~* \.(jpg|jpeg|png|gif)$ {
    # Matches image files (case-insensitive)
}

4. Prefix Match (^~)

Use ^~ for prefix matching. If the match is successful, stop searching immediately and don't check regex expressions.

nginx
location ^~ /static/ {
    # Matches URIs starting with /static/, no regex check
}

Matching Priority (High to Low):

1. Exact Match (=): Highest priority
2. Prefix Match (^~): If match succeeds, stop searching
3. Regex Match (~ and ~*): Check in configuration order
4. Prefix Match (No Modifier): Lowest priority

Matching Examples:

nginx
server {
    listen 80;
    server_name example.com;

    # 1. Exact match
    location = / {
        return 200 "Exact match /";
    }

    # 2. ^~ prefix match
    location ^~ /images/ {
        return 200 "Prefix match ^~ /images/";
    }

    # 3. Regex match (case-sensitive)
    location ~ \.php$ {
        return 200 "Regex match .php";
    }

    # 4. Regex match (case-insensitive)
    location ~* \.(jpg|jpeg|png|gif)$ {
        return 200 "Regex match images";
    }

    # 5. Regular prefix match
    location / {
        return 200 "Prefix match /";
    }
}

Actual Matching Results:

• Request / → Exact match location = /
• Request /images/logo.jpg → location ^~ /images/ (stops searching, no regex match)
• Request /test.php → location ~ \.php$
• Request /photo.JPG → location ~* \.(jpg|jpeg|png|gif)$ (case-insensitive)
• Request /other → location /

Nested Location:

nginx
location /api/ {
    # Outer location
    proxy_pass http://backend;

    location /api/v1/ {
        # Inner location, inherits outer configuration
        proxy_pass http://backend_v1;
    }
}

Usage Recommendations:

1. Place exact matches at the beginning
2. Place regex matches in the middle
3. Place regular prefix matches at the end
4. Use ^~ to avoid unnecessary regex matching
5. Use regex matching reasonably, avoid overuse affecting performance

Performance Considerations:

• Exact match and ^~ match have the best performance
• Regex matching requires compilation and execution, relatively lower performance
• Avoid using complex regex expressions
• Regex matches execute in configuration order, place commonly used matches first

Practical Use Cases:

nginx
# Static file caching
location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# PHP file handling
location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
}

# API request proxy
location /api/ {
    proxy_pass http://api_backend;
}

# Admin panel
location ^~ /admin/ {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://admin_backend;
}