Mastering NGINX Rewrites

Core NGINX Rewrite Directives

The return Directive: Simple & Efficient Redirects

For straightforward redirects or returning specific HTTP status codes, return is your go-to directive. It's the most efficient way to handle these cases as it immediately stops processing the request and sends the response to the client.

server {
    listen 80;
    server_name old-domain.com;
    # Permanent redirect for an entire domain
    return 301 $scheme://new-domain.com$request_uri;
}

location /old-page.html {
    # Permanent redirect for a specific page
    return 301 /new-page.html;
}

location /maintenance {
    # Return a 503 Service Unavailable status
    return 503 "Site is currently under maintenance.";
}
            

Variables to know:

• $scheme: The request scheme (http or https).
• $host: The hostname from the request line.
• $request_uri: The full original request URI with arguments (e.g., /path/to/page?param=value).

The rewrite Directive: Powerful Regex-Based URL Manipulation

When you need more complex URL manipulations based on regular expressions, the rewrite directive is your workhorse. It modifies the URI based on a regex pattern and a replacement string, optionally followed by a flag.

location /products/ {
    # Rewrites /products/category/item to /items?category=category&name=item
    rewrite ^/products/([^/]+)/([^/]+)$ /items?category=$1&name=$2 last;
}

location /blog/ {
    # Rewrites /blog/post-title to /index.php?page=post-title
    # This is an internal rewrite, NGINX continues processing
    rewrite ^/blog/(.*)$ /index.php?page=$1 break;
}
            

Common Flags:

• last: Stops processing the current set of ngx_http_rewrite_module directives and starts a new search for a location matching the rewritten URI. Useful for internal rewrites that might match another location.
• break: Stops processing the current set of ngx_http_rewrite_module directives. The rewritten URI is processed within the current location block.
• redirect: Returns a temporary redirect (302).
• permanent: Returns a permanent redirect (301).

The try_files Directive: The Front-Controller's Best Friend

try_files is incredibly powerful for serving static files efficiently and implementing front-controller patterns (like those used by WordPress, Laravel, Symfony, etc.). It tells NGINX to check for the existence of files or directories in a specified order, and if none are found, to internally redirect the request to a fallback URI.

location / {
    # For WordPress/Laravel type applications:
    # 1. Try to serve the exact URI as a file ($uri)
    # 2. If not a file, try to serve it as a directory ($uri/)
    # 3. If neither, internally redirect to index.php, preserving query arguments
    try_files $uri $uri/ /index.php?$args;
}

location ~ \.php$ {
    # Pass PHP requests to PHP-FPM
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php-fpm.sock; # Or fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}
            

Powerful NGINX Rewrite Tips

• Prioritize return for Simple Redirects: As mentioned, it's the most efficient. Use it whenever you just need to send a redirect or a fixed HTTP status code.
• Master try_files: This directive can simplify many common rewrite scenarios, especially for single-entry-point applications. Understand its order of operations.
• Avoid the if Directive When Possible: While NGINX has an if directive, its behavior can be tricky and lead to unexpected results, especially when combined with other directives. Often, careful use of location blocks and try_files can achieve the same results more reliably and performantly.
• Use Specific location Blocks: Define your location blocks as specifically as possible (e.g., exact matches =, prefix matches ^~, or regex matches ~/~*). This helps NGINX quickly determine which block to use, improving performance and clarity.
• Test Your Configuration Religiously: Always run sudo nginx -t before reloading NGINX after making changes. This command checks for syntax errors and potential issues, saving you from downtime.
• Understand NGINX Processing Order: NGINX processes directives in a specific order:
  1. server blocks (based on listen and server_name).
  2. location blocks (exact matches, then prefix matches, then regex matches).
  3. rewrite directives within a location block are processed sequentially.
  Understanding this flow is crucial for debugging and predicting behavior.
• Utilize Named Captures in Regex: For complex rewrites, use named captures (e.g., (?<name>regex)) to make your rewrite rules more readable and maintainable.
• Consider the map Directive for Large Sets: If you have a very large number of simple redirects or rewrites based on a single variable (e.g., old URLs to new URLs), the map directive can be more efficient than many individual rewrite rules.
• Enable rewrite_log for Debugging: During development or debugging, temporarily enable rewrite_log on; in your http, server, or location block. This will write detailed rewrite processing information to your error log, helping you understand how NGINX is interpreting your rules. Remember to turn it off in production.