Directiva rewrite în Nginx: sintaxă și exemple de configurare

Ce face `rewrite`

Directiva rewrite compară URI-ul cererii cu o expresie regulată PCRE și, dacă se potrivește, îl înlocuiește cu șirul specificat (în care $1, $2… reprezintă grupurile capturate între paranteze). Este instrumentul potrivit atunci când trebuie să extragi bucăți dintr-un URL vechi și să le recompui într-unul nou.

Al treilea parametru (flag-ul) controlează ce se întâmplă după rescriere: redirect (302) și permanent (301) trimit o redirecționare externă către browser; last oprește regulile rewrite curente și caută din nou un bloc location pentru noul URI; break oprește regulile rewrite și rămâne în blocul location curent.

Dacă tot ce vrei este să redirecționezi întregul site sau o cale fixă fără grupuri regex, preferă return 301 ... — este mai clar și nu compilează o expresie regulată.

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: server, location, if`	Se execută secvențial, în ordinea în care apar în bloc.
`regex`	Expresie regulată aplicată pe URI-ul normalizat (fără query string).
`înlocuire`	Noul URI sau URL; adaugă `?` la final (`/nou?`) dacă nu vrei ca parametrii GET vechi să fie lipiți automat.
`last`	Oprește `rewrite`-urile curente și reia căutarea unui `location` potrivit pentru noul URI.
`break`	Oprește `rewrite`-urile curente și continuă procesarea în același `location`.
`redirect`	Trimite clientului o redirecționare temporară `302`.
`permanent`	Trimite clientului o redirecționare permanentă `301`.

Exemple

Exemplul 1: Redirecționarea URL-urilor vechi de blog cu păstrarea slug-ului

Transformă /2024/05/titlu-articol.html în /blog/titlu-articol/ cu cod 301:

rewrite ^/\d{4}/\d{2}/([a-z0-9-]+)\.html$ /blog/$1/ permanent;

Exemplul 2: Rescriere internă către un script PHP

Vizitatorul vede în browser / profil/ana, dar intern este apelat /profil.php?user=ana:

location /profil/ {
    rewrite ^/profil/([a-z0-9_-]+)/?$ /profil.php?user=$1 last;
}

Exemplul 3: Eliminarea slash-ului final de la URL-urile care nu sunt directoare

Dacă nu există un director cu acel nume, redirecționează /despre/ către /despre:

if (!-d $request_filename) {
    rewrite ^/(.+)/$ /$1 permanent;
}

Greșeli frecvente

Bucle infinite de rescriere (eroarea rewrite or internal redirection cycle while processing... în error.log): apar când noul URI se potrivește din nou cu aceeași regulă (în special cu last în interiorul unui location). În location, de multe ori flag-ul potrivit este break.
Dublarea parametrilor din query string: Nginx adaugă automat vechiul query string la noul URI; dacă nu vrei asta, pune un ? la sfârșitul șirului de înlocuire (de exemplu rewrite ^/vechi$ /nou? permanent;).
Folosirea rewrite ^/(.*)$ https://example.com/$1 permanent; pentru HTTPS: return 301 https://$host$request_uri; face același lucru fără regex.

Comenzi înrudite

return: Oprește procesarea cererii și trimite imediat clientului un cod de stare HTTP, o redirecționare sau un text scurt.
Redirecționare HTTP → HTTPS: Tiparul recomandat pentru redirecționarea traficului de pe portul 80 pe HTTPS (și canonizarea cu sau fără www).
try_files: Verifică pe rând existența fișierelor sau directoarelor și redirecționează intern către ultimul argument dacă niciunul nu există.
location: Potrivește calea URI a cererii (exact, cu prefix sau cu expresie regulată) și aplică regulile corespunzătoare.

Ce face rewrite