expires în Nginx

expires [modified] timp | epoch | max | off;

Ce face expires

Directiva expires controlează cât timp păstrează browserul (și eventual un CDN) în cache fișierele statice (imagini, CSS, JavaScript, fonturi) fără a le mai descărca la fiecare pagină. O singură linie expires 30d; setează automat atât antetul Cache-Control: max-age=2592000, cât și antetul Expires cu data exactă peste 30 de zile.

Pentru fișierele ale căror nume conțin un hash de versiune generat la build (de exemplu app.8f3a9c.js), poți seta expires 1y; împreună cu Cache-Control "public, immutable": când codul se schimbă, se schimbă și numele fișierului, deci browserul nu va folosi niciodată o versiune veche.

În schimb, pentru fișierele HTML sau răspunsurile API care se schimbă frecvent, expires -1; (sau expires epoch;) setează Cache-Control: no-cache, obligând browserul să revalideze conținutul cu serverul.

Opțiuni și argumente

Opțiune / Parametru	Descriere
Context: http, server, location, if în location	Se pune de obicei într-un location care potrivește extensiile statice.
timp (30d, 12h, 1y)	Durata de păstrare în cache: s (secunde), m (minute), h (ore), d (zile), M (luni de 30 zile), y (ani de 365 zile).
-1 / epoch	Valoare negativă sau epoch: setează Cache-Control: no-cache.
max	Setează expirarea la 31 decembrie 2037 și max-age la 10 ani.
off	Nu adaugă și nu modifică antetele Expires și Cache-Control (comportamentul implicit).

Exemple

Exemplul 1: Durate diferite de cache după tipul fișierului

Folosind un bloc map pe $sent_http_content_type, nu mai ai nevoie de un location regex separat (care ar putea intra în conflict cu alte reguli):

# În contextul http:
map $sent_http_content_type $expires_by_type {
    default                    off;
    text/html                  epoch;
    text/css                   30d;
    application/javascript     30d;
    ~image/                    90d;
    ~font/                     1y;
    application/font-woff2     1y;
}

# În contextul server:
expires $expires_by_type;

Exemplul 2: Varianta clasică cu un bloc location pentru extensii statice

Simplă și directă pentru un site static sau WordPress:

location ~* \.(css|js|jpg|jpeg|png|gif|webp|avif|svg|ico|woff2?)$ {
    expires 30d;
    add_header Cache-Control "public, no-transform";
    access_log off;
}

Greșeli frecvente

• Setarea expires 30d; la nivel de server fără filtrare: și paginile HTML sau răspunsurile JSON dinamice vor fi păstrate în cache de browser timp de 30 de zile!
• Într-un reverse proxy (proxy_pass), un bloc location ~* \.(js|css|png)$ { expires 30d; } fără proxy_pass înăuntru face ca Nginx să caute acele fișiere pe discul local (și să dea 404) în loc să le ceară de la backend.

Comenzi înrudite

• gzip: Comprimă din mers răspunsurile text (HTML, CSS, JS, JSON, SVG) înainte de a le trimite către browser.
• add_header: Adaugă antete HTTP în răspunsul trimis clientului (antete de securitate HSTS, CSP, X-Frame-Options sau CORS).
• location: Potrivește calea URI a cererii (exact, cu prefix sau cu expresie regulată) și aplică regulile corespunzătoare.
• fastcgi_cache: Salvează în cache răspunsurile HTML generate de PHP-FPM, servind paginile direct din Nginx fără a mai apela PHP și baza de date.