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

Ce face `location`

Blocul location decide cum este procesată o cerere în funcție de URI-ul normalizat (calea de după domeniu, fără șirul de interogare ?a=1). Într-un bloc server pot exista mai multe blocuri location: unul pentru pagina principală, unul pentru fișierele statice, unul pentru /api/ sau pentru .php.

Ordinea în care Nginx evaluează blocurile nu este ordinea din fișier (cu excepția expresiilor regulate), ci urmează un algoritm în pași: 1) se verifică potrivirile exacte =; dacă una se potrivește, căutarea se oprește imediat; 2) se caută cel mai lung prefix (fără regex); dacă acel prefix are modificatorul ^~, căutarea se oprește și se folosește el; 3) se testează expresiile regulate ~ și ~* în ordinea în care apar în fișier și se alege prima care se potrivește; 4) dacă nicio expresie regulată nu s-a potrivit, se folosește cel mai lung prefix găsit la pasul 2.

Înțelegerea acestei priorități explică majoritatea surprizelor din configurările Nginx: de exemplu, de ce o regulă location ~ \.jpg$ are prioritate față de location /imagini/, dar nu și față de location ^~ /imagini/.

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: server, location`	Se scrie în `server` (și poate fi imbricat în alt `location`, cu unele restricții).
`(fără modificator)`	Potrivire după prefix: `location /api/` potrivește orice URI care începe cu `/api/`.
`=`	Potrivire exactă: `location = /login` potrivește doar `/login`, nu și `/login/`. Cea mai rapidă variantă.
`^~`	Potrivire după prefix cu prioritate: dacă acesta este cel mai lung prefix potrivit, expresiile regulate nu mai sunt verificate.
`~`	Expresie regulată PCRE sensibilă la majuscule/minuscule (case-sensitive).
`~*`	Expresie regulată PCRE insensibilă la majuscule/minuscule (de exemplu `\.(jpg\|png)$` potrivește și `.JPG`).
`@nume`	Locație numită, folosită doar pentru redirecționări interne (de exemplu în `try_files` sau `error_page`).

Exemple

Exemplul 1: Ordinea de evaluare pe un caz concret

Toate cele patru tipuri de location în același server:

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com/public;

    # 1. Potrivire exactă pentru / — oprește căutarea imediat
    location = / {
        try_files /index.html =404;
    }

    # 2. Prefix general (fallback pentru orice URI)
    location / {
        try_files $uri $uri/ =404;
    }

    # 3. Prefix cu ^~ — nu lasă regex-ul de mai jos să preia /static/logo.png
    location ^~ /static/ {
        expires 30d;
    }

    # 4. Regex insensibil la majuscule pentru imagini din alte directoare
    location ~* \.(jpg|jpeg|png|gif|webp|svg|ico)$ {
        expires 7d;
        access_log off;
    }
}

Exemplul 2: Blocarea accesului la fișierele ascunse (.git, .env)

Permitem doar /.well-known/ (folosit de Let’s Encrypt) și blocăm orice alt fișier sau director care începe cu punct:

location ^~ /.well-known/ {
    allow all;
}

location ~ /\.(?!well-known).* {
    deny all;
    access_log off;
    log_not_found off;
}

Exemplul 3: Locație numită (@backend) ca fallback

Dacă fișierul nu există pe disc, cererea este trimisă intern către @backend:

location / {
    try_files $uri @backend;
}

location @backend {
    proxy_pass http://127.0.0.1:3000;
}

Greșeli frecvente

A încerca să potrivești parametrii din query string (?page=2) în location: location vede doar calea. Pentru ?page=2 se verifică variabila $args sau $arg_page.
A presupune că ordinea din fișier contează pentru blocurile cu prefix: dintre location /api/ și location /api/v2/ câștigă întotdeauna cel mai lung (/api/v2/), indiferent care este scris primul.
Definirea root doar într-un singur location: celelalte location nu îl moștenesc și folosesc directorul implicit al compilării Nginx. Pune root direct în server.

Comenzi înrudite

server: Definește un server virtual (un site) cu porturile, numele de domeniu și regulile sale.
root / alias: Stabilesc directorul de pe disc din care sunt servite fișierele: root lipește întregul URI, alias înlocuiește prefixul location.
try_files: Verifică pe rând existența fișierelor sau directoarelor și redirecționează intern către ultimul argument dacă niciunul nu există.
rewrite: Modifică URI-ul cererii pe baza unei expresii regulate, pentru redirecționări externe sau rescrieri interne.

Ce face location