Règles de correspondance des locations Nginx expliquées avec des exemples concrets

Vous avez probablement modifié une configuration Nginx, rechargé, et vous vous êtes demandé pourquoi votre bloc location ne s'appliquait pas. Peut-être qu'une requête de fichier statique atteint votre gestionnaire PHP, ou qu'une route API est engloutie par un catch-all. Le coupable est souvent l'algorithme de correspondance des locations de Nginx—il n'est pas aussi simple qu'il n'y paraît.

Dans ce guide, nous allons décomposer comment Nginx sélectionne un bloc location, avec des exemples concrets que vous pouvez tester. À la fin, vous saurez exactement quel bloc gagne et pourquoi.

Comment fonctionne la correspondance des locations Nginx

Lorsqu'une requête arrive, Nginx compare l'URI avec tous les blocs location définis. Le processus de correspondance suit un ordre spécifique :

1. Correspondance exacte (=) — priorité la plus élevée. Si trouvée, Nginx s'arrête et l'utilise.
2. Correspondance de préfixe la plus longue — Nginx retient la location de préfixe correspondante la plus longue.
3. Correspondance d'expression régulière (~ ou ~*) — vérifiée dans l'ordre d'apparition. La première regex qui correspond gagne, en écrasant la correspondance de préfixe (sauf si ^~ est utilisé).
4. Correspondance de préfixe avec ^~ — si le préfixe correspondant le plus long a ^~, Nginx ignore la vérification des regex et l'utilise.
5. Si aucune regex ne correspond, la correspondance de préfixe la plus longue est utilisée.

C'est le cœur de l'algorithme. Voyons-le en action.

Modificateurs de location : référence rapide

Exemple concret 1 : Fichiers statiques vs. PHP

Considérez cette configuration courante :

server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/html;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

Une requête pour /index.php correspond à la regex \.php$, donc elle va vers PHP-FPM. Une requête pour /logo.png ne correspond pas à la regex, donc elle retombe sur le préfixe / et sert le fichier statique. Simple, non ?

Mais que se passe-t-il si vous voulez servir /uploads/photo.php comme fichier statique (peut-être qu'il s'agit en fait d'une image) ? Vous pouvez ajouter une correspondance exacte :

location = /uploads/photo.php {
    root /var/www/html;
}

Maintenant, cette correspondance exacte prend le pas sur la regex.

Exemple concret 2 : Routage API avec préfixe et regex

Supposons que vous ayez une API sous /api/ et que vous vouliez proxyfier toutes les requêtes vers un backend, sauf pour un health check qui renvoie une réponse statique.

location = /api/health {
    return 200 "OK";
}

location /api/ {
    proxy_pass http://backend;
}

location ~ ^/api/v[0-9]+/special {
    proxy_pass http://special-backend;
}

Traçons /api/health : la correspondance exacte gagne, renvoie 200. Pour /api/users : pas d'exacte, pas de regex (ne correspond pas à special), donc le préfixe le plus long /api/ est utilisé. Pour /api/v1/special : la regex correspond, donc elle écrase le préfixe et va vers special-backend.

Cela démontre comment une regex peut écraser une correspondance de préfixe. Si vous vouliez que le préfixe gagne toujours, vous utiliseriez ^~ à la place.

Exemple concret 3 : La puissance de ^~

Imaginez que vous ayez un répertoire /static/ avec des fichiers qui ne doivent jamais être traités par PHP, même s'ils se terminent par .php. Utiliser ^~ garantit que Nginx ne vérifie pas les locations regex.

location ^~ /static/ {
    root /var/www/html;
}

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Une requête pour /static/script.php correspond au préfixe ^~ /static/. À cause de ^~, Nginx ignore la vérification regex et sert le fichier directement. Sans ^~, la regex correspondrait et PHP-FPM l'exécuterait—un risque de sécurité potentiel.

Pièges courants et comment les éviter

• L'ordre des regex compte : Nginx vérifie les locations regex dans l'ordre où elles apparaissent dans la configuration. Placez les motifs plus spécifiques en premier.
• Barres obliques finales manquantes : location /api et location /api/ sont différents. Le premier correspond à /api et /apix, tandis que le second correspond à /api/ et /api/users. Soyez précis.
• Préfixes qui se chevauchent : Le préfixe le plus long gagne, donc location /api/v1 prend le pas sur location /api pour /api/v1/users.
• Oublier ^~ pour les ressources statiques : Utilisez-le pour empêcher les regex de détourner les requêtes de fichiers statiques.
• Sensibilité à la casse : ~ est sensible à la casse, ~* ne l'est pas. Utilisez ~* pour les extensions de fichiers.

Débogage de la correspondance des locations

Si vous n'êtes pas sûr de la location utilisée, activez la journalisation de débogage dans Nginx. Ajoutez error_log /var/log/nginx/error.log debug; dans votre bloc server, rechargez, et consultez le journal. Vous verrez des lignes comme test location: "/api/users" et using configuration "/api/".

Alternativement, utilisez temporairement return 200 "matched: /api/"; dans chaque location pour voir laquelle répond.

FAQ

Quel est l'ordre de priorité des modificateurs de location Nginx ?

La correspondance exacte (=) est la plus élevée, puis le préfixe le plus long avec ^~, puis la regex (~ ou ~*) dans l'ordre, puis la correspondance de préfixe la plus longue sans ^~.

Une location regex peut-elle écraser une location de préfixe ?

Oui, sauf si la location de préfixe utilise ^~. Les locations regex sont vérifiées après la correspondance de préfixe la plus longue, et si une regex correspond, elle prend le pas sur un préfixe régulier.

Comment faire correspondre une location uniquement pour un fichier spécifique ?

Utilisez une correspondance exacte avec =, par exemple location = /favicon.ico. Cela garantit que seul cet URI exact est mis en correspondance.

Maîtrisez votre configuration Nginx

Comprendre la correspondance des locations est essentiel pour une configuration Nginx fiable. Testez vos configurations avec nginx -t et utilisez les journaux de débogage en cas de doute. Si vous analysez des journaux Nginx et avez besoin d'examiner les modèles de trafic, essayez notre Analyseur de journaux Nginx pour analyser et visualiser vos journaux rapidement.