Rewrite & Redirect

What Are Rewrite & Redirect Rules?

In NGINX, rewrite and redirect rules control how incoming URLs are handled:

• Rewrite → Internally changes the URI without telling the browser
• Redirect → Sends a response to the browser telling it to go to a different URL

They are commonly used for:

• SEO-friendly URLs
• Enforcing HTTPS
• Removing www or adding www
• Legacy URL migration
• API versioning
• Language or country routing

Rewrite vs Redirect (Key Difference)

Feature	Rewrite	Redirect
Browser URL changes?	❌ No	✅ Yes
Client aware?	❌ No	✅ Yes
HTTP status code	Not visible	301, 302, etc.
Performance	Faster	Slightly slower
SEO impact	Neutral	Very important

rewrite Directive (Internal URL Rewrite)

Basic Syntax

rewrite regex replacement [flag];

Example: Remove .php from URLs

• URL Requested: /about
• Actual File: /about.php

location / {
    rewrite ^/([a-zA-Z0-9_-]+)$ /$1.php last;
}

• ^/([a-zA-Z0-9_-]+)$ → Matches /about
• $1.php → Converts it to /about.php
• last → Re-process the request with the new URI
• Browser still shows /about

Rewrite Flags (Very Important)

Flag	Meaning
last	Re-evaluates location blocks
break	Stops rewrite processing
redirect	Temporary redirect (302)
permanent	Permanent redirect (301)

Redirect Using rewrite

Example: HTTP → HTTPS Redirect

server {
    listen 80;
    server_name example.com;

    rewrite ^ https://example.com$request_uri permanent;
}

• Redirects all HTTP traffic to HTTPS
• permanent sends 301
• $request_uri preserves path & query string

Not recommended for complex logic (use return instead)

Redirect Using return (Best Practice)

Example: HTTP → HTTPS (Recommended)

server {
    listen 80;
    server_name example.com;

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

Why return is Better: Faster, Clear, No regex evaluation, Best for simple redirects

Remove www from Domain

server {
    listen 80;
    server_name www.example.com;

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

• Forces a single canonical domain
• Improves SEO
• Avoids duplicate content

Add www to Domain

server {
    listen 80;
    server_name example.com;

    return 301 https://www.example.com$request_uri;
}

Redirect Old URLs to New URLs (SEO Migration)

• Old URL: /old-blog/my-post
• New URL: /blog/my-post

rewrite ^/old-blog/(.*)$ /blog/$1 permanent;

• Captures everything after /old-blog/
• Redirects with 301
• Preserves SEO ranking

Conditional Rewrite with if (Use Carefully)

if ($request_method = POST) {
    rewrite ^/submit$ /submit.php last;
}

if in NGINX can be dangerous if misused
Safe when used for simple conditions like redirects

Language-Based Redirect

location / {
    if ($http_accept_language ~* "^fr") {
        return 302 /fr;
    }
}

• Detects browser language
• Redirects French users to /fr
• Temporary redirect (302)

Rewrite for API Versioning

location /api/ {
    rewrite ^/api/v1/(.*)$ /api/$1 break;
}

• Keeps backend simple
• Allows multiple API versions
• Internal rewrite only

Regex Capture Variables

rewrite ^/product/([0-9]+)$ /item.php?id=$1 last;

• Example Request: /product/123
• Result: /item.php?id=123

Common Mistakes

• Using rewrite instead of return
• Redirect loops
• Too many regex rules
• Using if for complex logic
• Forgetting last or break