location в nginx: как выбирается блок для адреса

Виды location

nginx сравнивает только путь — часть адреса до знака ?. Параметры после него в выборе не участвуют. Перед сравнением путь приводится к одному виду: коды вида %20 раскодируются, /a/../b превращается в /b, двойные слэши склеиваются.

Как nginx выбирает блок

1. Сравнивает путь со всеми префиксными location. Совпадение с location = — сразу берёт этот блок. Иначе запоминает самый длинный совпавший префикс.
2. Если у этого префикса стоит ^~, берёт его — регулярные выражения не проверяет.
3. Проверяет регулярные выражения по порядку, как они записаны в файле. Первое совпавшее побеждает.
4. Если ни одно регулярное выражение не подошло, берёт запомненный префикс.

Порядок префиксных блоков в файле не важен — побеждает самый длинный. Порядок регулярных выражений важен — побеждает первое.

Пример

location = / {               # блок А
}
location / {                 # блок Б
}
location /docs/ {            # блок В
}
location ^~ /img/ {          # блок Г
}
location ~* \.(png|jpg)$ {   # блок Д
}

Вложенные location

Блок location можно написать внутри другого. Внутренний префикс должен начинаться с внешнего: внутри location /blog/ можно location /blog/img/, а location /img/ nginx не примет. Регулярные выражения внутри могут быть любыми:

location /blog/ {
    location ~* \.jpe?g$ {
        expires 30d;
    }
}

Здесь картинки JPEG из /blog/ браузер будет хранить у себя 30 дней — подробнее о expires. Внутри location = и location @имя других блоков быть не может, а именованный location пишут только прямо в server.

Слэш в конце и переадресация 301

Если location записан со слэшем в конце, например location /app/, и запросы из него уходят приложению через proxy_pass или в PHP через fastcgi_pass, то на адрес без слэша — /app — nginx ответит переадресацией 301 на /app/. Если это не нужно, добавьте отдельный блок для точного адреса:

location = /app {
    proxy_pass http://127.0.0.1:3000;
}

Как работает proxy_pass и при чём тут слэш в конце адреса — proxy_pass в nginx.

Ошибки и как их исправить

Какой блок обработал запрос, проще всего проверить своим заголовком: добавьте в location строку add_header X-Block docs; и посмотрите ответ командой curl -I https://example.com/docs/guide.html. После проверки строку уберите. Как работает add_header — на отдельной странице.