Prefix match in Nginx - Commands & Configuration

Introduction

Sometimes you want your web server to respond differently based on the beginning part of a website address. Prefix match lets you do this by checking if a URL starts with a certain path and then applying special rules for it.

When you want to serve different content for URLs starting with /images versus other URLs.

When you want to redirect all URLs starting with /blog to a new location.

When you want to apply security rules only to URLs starting with /admin.

When you want to cache all requests starting with /static differently.

When you want to proxy requests starting with /api to a backend server.

Config File - nginx.conf

nginx.conf

events {}
http {
    server {
        listen 80;
        server_name example.com;

        location /images/ {
            root /var/www;
        }

        location /blog/ {
            return 301 https://blog.example.com$request_uri;
        }

        location /admin/ {
            auth_basic "Restricted Area";
            auth_basic_user_file /etc/nginx/.htpasswd;
        }

        location / {
            root /var/www/html;
        }
    }
}

This configuration sets up an Nginx server listening on port 80 for example.com.

The location /images/ block matches any URL starting with /images/ and serves files from /var/www/images.

The location /blog/ block matches URLs starting with /blog/ and redirects them to a new blog domain.

The location /admin/ block matches URLs starting with /admin/ and requires a password to access.

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

Commands

Check the Nginx configuration file for syntax errors before applying it.

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)

Test that a URL starting with /images/ serves the correct content.

Terminal

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

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: image/png

...

Test that a URL starting with /blog/ redirects to the new blog domain.

Terminal

curl -I http://example.com/blog/post1

Expected Output

HTTP/1.1 301 Moved Permanently

Location: https://blog.example.com/blog/post1

Server: nginx

...

Test that a URL starting with /admin/ requires authentication.

Terminal

curl -I http://example.com/admin/dashboard

Expected Output

HTTP/1.1 401 Unauthorized

WWW-Authenticate: Basic realm="Restricted Area"

Server: nginx

...

Key Concept

If you remember nothing else from this pattern, remember: Nginx matches URLs by checking if they start with the prefix you specify in the location block.

Common Mistakes

Using location blocks without trailing slashes for prefix matching.

Nginx treats location without trailing slash differently, which can cause unexpected matches or misses.

Always include the trailing slash in the location prefix when you want to match URL beginnings, like /images/.

Placing a more general location block before a more specific one.

Nginx uses the longest prefix match, but order can affect regex locations; general blocks may override specific ones if misconfigured.

Put specific prefix location blocks before general ones and avoid regex conflicts.

Summary

Use location blocks with a trailing slash to match URL prefixes in Nginx.

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

Reload Nginx to apply changes without downtime.

Use curl commands to verify that prefix matches behave as expected.