Конфигурация Nginx: как связаны server, location и root

Почему Nginx отдаёт 404, хотя файл на диске есть

Если в Nginx указать правильную папку в root, сайт всё равно может отвечать 404: запрос попал не в тот server или location, а путь к файлу собрался не так, как вы ожидали. Ниже — схема для Nginx 1.24 и новее: как выбрать виртуальный сервер, сопоставить URI с location и понять, какой файл получится на диске. В примере используется статический сайт и маршрутизация через try_files.

Сначала разложите конфигурацию по уровням

Конфигурация Nginx вложенная. Основные правила обычно находятся в контексте http, а сайт описывают внутри server. Внутри него могут быть несколько блоков location.

• server выбирает виртуальный сервер по адресу назначения и заголовку Host.
• location сопоставляет URI запроса с правилом обработки.
• root задаёт каталог, к которому Nginx добавляет URI, чтобы получить путь к файлу.

Это разные задачи. server не указывает папку сайта, а location сам по себе не создаёт файл и не гарантирует, что запрос уйдёт в нужный каталог.

Проверяйте не только значение root, но всю цепочку: какой server выбран, какой location сработал и какой путь Nginx в итоге проверяет.

Как Nginx выбирает server и location

Сначала — блок server

Nginx учитывает адрес и порт, на которых принимает соединение, а затем сравнивает имя хоста с директивами server_name. Если подходящего имени нет, запрос обрабатывает сервер по умолчанию для этого адреса и порта. Поэтому правка root в одном блоке не поможет, если запрос обслуживает другой.

Для диагностики проверьте, что домен указывает на нужный сервер, Nginx слушает ожидаемый порт, а имя присутствует в server_name. У одного IP могут быть несколько блоков server: это штатный способ обслуживать несколько сайтов.

Затем — location

Nginx сравнивает URI без строки запроса: в /catalog/item?id=7 для выбора location важна часть /catalog/item. Упрощённо порядок такой: сначала проверяется точное совпадение =, затем выбирается самый длинный префикс. Если у него нет модификатора ^~, Nginx проверяет регулярные выражения по порядку и использует первое совпавшее. Если регулярное выражение не подошло, остаётся выбранный префикс.

Из-за этого блоки нельзя читать как список правил, которые все применяются одновременно. Например, отдельный location для изображений может перехватить запрос раньше общего правила для сайта.

Что именно делает root

Когда Nginx ищет файл по правилу с root, он добавляет URI к указанному каталогу. Если root равен /srv/www/shop, а запрос пришёл на /assets/logo.svg, проверяемый путь будет /srv/www/shop/assets/logo.svg. Важен URI целиком, включая его начальный слеш; Nginx не заменяет его именем выбранного location.

Директиву root можно задавать в контекстах http, server и location. Если значение указано на нескольких уровнях, действует наиболее близкое к запросу: настройка в location перекрывает значение из server. Эта особенность удобна для отдельных каталогов, но может неожиданно направить запросы не туда.

Не путайте root и alias. Alias заменяет совпавшую часть URI путём, заданным в location; это другой способ сопоставить URL с каталогом. Здесь разбираем root: если нужен alias, сверяйте правила и примеры в документации Nginx.

URI¹ — часть адреса после домена и до параметров запроса. Например, в https://example.com/docs/start?lang=ru URI — /docs/start.

Пример: статический сайт и резервный маршрут

Конфигурация ниже рассчитана на Nginx 1.24 и новее. Она предполагает, что файлы сайта лежат в /srv/www/shop, а запросы к несуществующим путям должны передаваться приложению через фронтенд-файл index.html. Если такого файла нет, резервный маршрут тоже вернёт ошибку.

server {
    listen 80;
    server_name example.com www.example.com;

    root /srv/www/shop;
    index index.html;

    location = /health {
        return 200 "ok\n";
    }

    location /assets/ {
        try_files $uri =404;
    }

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

В первом location точное совпадение обрабатывает запрос /health. Блок /assets/ ищет запрошенный файл и возвращает 404, если его нет. Общий location сначала проверяет файл по URI, затем каталог, а после неудачи внутренне перенаправляет обработку на /index.html. Само перенаправление не означает, что файл существует: он должен лежать в root.

Для примера /assets/logo.svg путь проверки — /srv/www/shop/assets/logo.svg. Для /products/42 Nginx сначала проверит файл и каталог под таким путём, а затем попробует отдать /srv/www/shop/index.html. Проверьте владельца и права доступа к файлам: наличие файла на диске не помогает, если процесс Nginx не может прочитать каталог или файл.

Перед перезагрузкой проверьте синтаксис командой nginx -t. Если проверка прошла, конфигурацию можно перечитать командой nginx -s reload; способ управления сервисом может отличаться в зависимости от системы и установки.

Что чаще всего ломается

• Не тот server. Домен или порт не совпадает с ожидаемыми. Проверьте DNS, listen, server_name и конфигурацию виртуальных серверов.
• Неверный путь. URI добавляется к root, поэтому для /assets/app.css проверяется путь с каталогом assets. Сопоставьте его с реальным расположением файла.
• Файл доступен оболочке, но не Nginx. Проверьте права на сам файл и все каталоги выше него, а также пользователя, от которого работает Nginx.
• Регулярное выражение перехватило запрос. Проверьте порядок location с регулярными выражениями и наличие ^~ у префикса, если regex не должен вмешиваться.
• Резервный файл отсутствует. В try_files указан /index.html, но файла нет в root. Проверьте сборку и путь публикации.

Для проверки конкретного запроса полезны журналы доступа и ошибок Nginx. Смотрите время запроса, код ответа, выбранный виртуальный сервер и сообщение о пути, который не удалось открыть. Не публикуйте журналы с приватными URL, токенами или персональными данными.

Что проверить дальше

Возьмите один URL, который работает неправильно, и разберите его по цепочке: какой адрес и порт принимает соединение, какой server подходит по имени, какой location совпадает, какое значение root действует и какой путь получается на диске. После этого проверьте права доступа и журналы. Если сайт работает за прокси или использует PHP, правила передачи запроса приложению — отдельная часть конфигурации; не добавляйте её наугад к примеру выше.

¹ URI — идентификатор ресурса в запросе; здесь речь о пути, по которому клиент обращается к ресурсу на сайте.