try_files în Nginx

try_files fișier ... uri;
try_files fișier ... =cod;

Ce face try_files

Directiva try_files verifică, în ordinea scrisă, dacă există pe disc fișierele sau directoarele specificate (raportate la root sau alias). Primul care există este servit. Dacă niciunul nu este găsit, Nginx face o redirecționare internă către ultimul parametru (care poate fi un URI, o locație numită @nume sau un cod de stare precum =404).

Pentru a verifica existența unui director, adaugă un slash la sfârșit: $uri/. Astfel, expresia clasică try_files $uri $uri/ =404; înseamnă: „încearcă mai întâi ca fișier exact; dacă nu este fișier, încearcă-l ca director (caz în care se caută fișierul index); dacă nu există nici așa, răspunde cu 404”.

În aplicațiile moderne (WordPress, Laravel, Symfony, React/Vue SPA), try_files înlocuiește vechile reguli if (!-e $request_filename) din Apache/Nginx: orice cerere care nu corespunde unui fișier real (CSS, imagine) este trimisă la /index.php?$query_string sau la /index.html.

Opțiuni și argumente

Opțiune / Parametru	Descriere
Context: server, location	Se scrie aproape întotdeauna în location / sau în blocul location ~ \.php$.
$uri	Calea cerută de client; verifică dacă există un fișier cu acel nume.
$uri/	Cu slash la final, verifică dacă există un director cu acel nume (și aplică directiva index).
uri final	Ultimul parametru fără = face o redirecționare internă (de exemplu /index.php?$args sau @backend).
=cod	Dacă ultimul parametru este de forma =404, Nginx returnează direct acel cod HTTP.

Exemple

Exemplul 1: Front controller pentru WordPress / Laravel / Symfony

Fișierele reale (imagini, CSS) sunt servite direct de pe disc; orice altă adresă ajunge la index.php cu parametrii GET păstrați:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Exemplul 2: Aplicație Single-Page (React, Vue, Angular)

Rutele din browser (/profil, /setari) nu sunt fișiere pe disc, așa că toate primesc /index.html, iar routerul JavaScript afișează pagina corectă:

server {
    listen 80;
    server_name app.example.com;
    root /var/www/app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Pentru fișierele statice lipsă vrem 404 real, nu index.html
    location /assets/ {
        try_files $uri =404;
        expires 1y;
    }
}

Exemplul 3: Pagină statică de mentenanță activată printr-un fișier

Cât timp există pe disc /var/www/site/public/maintenance.html, toate cererile îl primesc:

location / {
    try_files /maintenance.html $uri $uri/ /index.php?$args;
}

Greșeli frecvente

• Un singur argument în try_files (de exemplu try_files $uri;): sintaxa cere cel puțin două argumente (ce se încearcă + ce se face în caz de eșec).
• Uitarea ?$query_string (sau ?$args) la /index.php: parametrii din URL precum ?s=cautare&page=2 se pierd.
• Trimiterea .php inexistente la PHP-FPM fără verificare: în location ~ \.php$ adaugă try_files $uri =404; (sau include snippets/fastcgi-php.conf, care îl conține deja).

Comenzi înrudite

• location: Potrivește calea URI a cererii (exact, cu prefix sau cu expresie regulată) și aplică regulile corespunzătoare.
• root / alias: Stabilesc directorul de pe disc din care sunt servite fișierele: root lipește întregul URI, alias înlocuiește prefixul location.
• fastcgi_pass: Trimite scripturile .php către PHP-FPM prin protocolul FastCGI (socket Unix sau port TCP).
• rewrite: Modifică URI-ul cererii pe baza unei expresii regulate, pentru redirecționări externe sau rescrieri interne.