Preferential prefix match (^~) in Nginx - Commands & Configuration

Introduction

Sometimes you want nginx to match a URL prefix exactly and stop searching for other matches. The ^~ prefix tells nginx to use this location if the URL starts with the given prefix, ignoring regex locations. This helps serve specific paths faster and more predictably.

When you want to serve static files from a specific folder without regex slowing down matching.

When you have a URL prefix that should always use a certain configuration, ignoring regex rules.

When you want to improve performance by avoiding regex checks for common URL prefixes.

When you want to make sure a certain path is handled by a specific location block without surprises.

When you want to simplify URL routing by prioritizing prefix matches over regex matches.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location ^~ /images/ {
        root /var/www/static;
        # This serves all requests starting with /images/ from /var/www/static/images/
    }

    location ~* \.(jpg|jpeg|png|gif)$ {
        # Regex location for image files
        expires 30d;
    }

    location / {
        proxy_pass http://localhost:3000;
    }
}

The location ^~ /images/ block tells nginx to use this block for any URL starting with /images/ and stop searching further, ignoring regex locations.

The location ~* \.(jpg|jpeg|png|gif)$ block is a regex match for image files, but it will be ignored if the URL starts with /images/ because of the ^~ prefix.

The location / block is the default catch-all for other requests.

Commands

Check the nginx configuration file syntax to make sure there are no errors before reloading.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request to check headers for a file under /images/ to confirm the ^~ prefix location is used.

Terminal

curl -I http://example.com/images/logo.png

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: image/png

Content-Length: 12345

Last-Modified: Wed, 01 Jan 2020 12:00:00 GMT

Connection: keep-alive

Send a request for an image file outside /images/ to confirm regex location is used for caching headers.

Terminal

curl -I http://example.com/picture.jpg

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: image/jpeg

Expires: Thu, 01 Aug 2024 12:00:00 GMT

Cache-Control: max-age=2592000

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: the ^~ prefix tells nginx to use this location block for matching URL prefixes and skip regex checks.

Common Mistakes

Using regex location (~) before a ^~ prefix location for the same URL prefix.

nginx will ignore the regex location if a ^~ prefix location matches first, causing unexpected behavior.

Use ^~ for prefix matches you want to prioritize and avoid conflicting regex locations for the same prefix.

Not testing nginx configuration before reload.

Syntax errors can cause nginx to fail to reload, leading to downtime.

Always run 'nginx -t' to verify configuration syntax before reloading.

Summary

Use the ^~ prefix in nginx location blocks to prioritize prefix matches over regex matches.

Test nginx configuration syntax with 'nginx -t' before reloading to avoid errors.

Reload nginx with 'systemctl reload nginx' to apply changes without downtime.

Verify location matching by sending HTTP requests to URLs under the prefix and outside it.