Директива location в Nginx: Полное руководство с примерами

Введение

Директива location — основной механизм маршрутизации в Nginx, определяющий, как сервер сопоставляет входящие запросы с конфигурацией: откуда отдать статичный контент, куда перенаправить трафик или как переписать URL.

Почему это важно? Каждый запрос к серверу Nginx должен быть обработан в блоке location. Ошибки в конфигурации ведут к некорректной маршрутизации: запросы могут попасть не в тот бэкенд, не найти статические файлы или обойти правила безопасности. Понимание принципов работы location — ключ к корректной, эффективной и безопасной настройке веб-сервера.

В этой статье подробно разбирается синтаксис директивы, алгоритм выбора location (порядок приоритетов), а также приводятся практические примеры: от обслуживания статических файлов до настройки reverse proxy. Отдельное внимание уделяется разнице между root и alias, методам отладки конфигурации и её оптимизации для повышения производительности.

Синтаксис директивы location: модификаторы и их значение

Директива location определяет, как Nginx сопоставляет URI входящего запроса с файловыми путями на сервере или целями для проксирования. Блоки location могут размещаться внутри блоков server или быть вложенными в другие блоки location (с определёнными ограничениями).

Базовый синтаксис:

location [модификатор] [URI] {
    # директивы
}

Модификатор — необязательный параметр, но он кардинально меняет поведение при сопоставлении. URI может быть строкой для точного или префиксного совпадения, либо регулярным выражением.

Таблица модификаторов location

Зачем нужны модификаторы? Без модификатора Nginx выполняет префиксное совпадение, но продолжает проверять все regex-блоки в конфигурации. Использование ^~ останавливает проверку regex после префиксного совпадения, что повышает производительность. Модификатор = имеет наивысший приоритет, но работает только для абсолютно точных путей — его используют для конкретных endpoints, например, /favicon.ico или /health.

# Точное совпадение - наивысший приоритет
location = /images {
    # Совпадёт ТОЛЬКО с URI "/images", но не с "/images/" или "/images/logo.png"
}

# Префиксное совпадение, останавливающее проверку regex
location ^~ /images {
    # Совпадёт с "/images", "/images/", "/images/logo.png"
    # Проверка regex-локаций после этого блока НЕ производится
}

# Регистрозависимое регулярное выражение
location ~ \.(jpg|png|gif)$ {
    # Совпадёт с файлами .jpg, .png, .gif (регистр важен: .JPG НЕ совпадёт)
}

# Регистронезависимое регулярное выражение
location ~* \.(jpg|png|gif)$ {
    # Совпадёт с .JPG, .PNG, .GIF, .jpg, .png, .gif
}

Алгоритм выбора location: порядок сопоставления в Nginx

Понимание алгоритма выбора блока location критически важно для создания предсказуемых конфигураций. Nginx оценивает блоки не по принципу «первое совпадение», а по строгой последовательности, которая гарантирует приоритет точных и префиксных совпадений над регулярными выражениями.

Последовательность шагов алгоритма

Когда Nginx получает запрос, он выполняет следующие шаги для выбора location:

Шаг 1: Проверка точного совпадения (=)

• Сначала Nginx ищет блок location с модификатором =, путь которого полностью идентичен URI запроса.
• Если такое совпадение найдено — поиск немедленно прекращается, и используется этот блок.
• Пример: location = /api совпадёт только с запросом /api, но не с /api/ или /api/users.

Шаг 2: Поиск самого длинного префиксного совпадения (без ^~)

• Nginx анализирует все блоки location без модификаторов и с модификатором ^~, находя вариант с максимальной длиной совпадающего префикса.
• Если самый длинный префиксный блок использует модификатор ^~, алгоритм останавливается на этом шаге, и запрос обрабатывается этим блоком.
• Если самый длинный префиксный блок не использует ^~, этот результат запоминается как временный, и выполнение переходит к шагу 3.

Шаг 3: Проверка регулярных выражений (~ и ~*)

• Nginx проверяет regex-локации (~ и ~*) в том порядке, в котором они объявлены в конфигурационном файле.
• Используется первое регулярное выражение, которое совпадает с URI запроса.
• Если regex-совпадение найдено, оно переопределяет запомненное на шаге 2 префиксное совпадение.

Шаг 4: Возврат к префиксному совпадению

• Если на шаге 3 ни одно регулярное выражение не совпало, Nginx использует запомненный на шаге 2 самый длинный префиксный блок.
• Если нет ни одного подходящего префиксного блока, запрос обрабатывается блоком location / (универсальным обработчиком).

# НЕПРАВИЛЬНЫЙ ПОРЯДОК: Менее специфичное правило стоит первым
location ~ /api {
    # Это правило сработает для "/api/users"
}

location ~ /api/users {
    # Это правило НИКОГДА не сработает для "/api/users"
    # т.к. первый regex уже совпал и поиск прекращён
}

# ПРАВИЛЬНЫЙ ПОРЯДОК: От наиболее специфичного к общему
location ~ /api/users {
    # Правило для конкретного пути
}

location ~ /api {
    # Общее правило для остальных запросов к /api
}

Визуализация процесса выбора

Рассмотрим запрос GET /images/icon.png к следующей конфигурации:

location = /images/logo.png { ... }
location ^~ /images/ { ... }
location / { ... }
location ~ \.png$ { ... }

1. Точное совпадение: location = /images/logo.png — нет совпадения (путь не идентичен).
2. Самый длинный префикс: location ^~ /images/ — совпадение найдено. Поскольку используется модификатор ^~, поиск немедленно прекращается.
3. Проверка regex: Блок location ~ \.png$ не проверяется, так как шаг 2 был остановлен.
4. Результат: Обработка запроса выполняется в блоке location ^~ /images/.

Практический пример: демонстрация приоритетов

server {
    listen 80;
    server_name example.com;

    # Regex-локация — проверяется ПОСЛЕ префиксных
    location ~ /api/v1 {
        return 200 "API v1";
    }

    # Префиксное совпадение с остановкой regex
    location ^~ /api {
        return 200 "API prefix";
    }

    # Точное совпадение — наивысший приоритет
    location = /api {
        return 200 "API exact";
    }

    # Универсальный обработчик
    location / {
        return 200 "Default";
    }
}

Результаты тестов:

• curl http://example.com/api → "API exact" (точное совпадение приоритетнее)
• curl http://example.com/api/users → "API prefix" (^~ остановил проверку regex)
• curl http://example.com/api/v1/users → "API prefix" (^~ совпал с /api и остановил проверку regex для /api/v1)

Базовые примеры блоков location

В этом разделе разобраны типовые шаблоны использования директивы location, которые составляют основу большинства конфигураций.

Пример 1: Универсальный обработчик (Catch-All)

Блок location / обрабатывает все запросы, которые не совпали с более специфичными правилами. Это обработчик по умолчанию (fallback).

location / {
    root /var/www/html;
    index index.html index.htm;
    try_files $uri $uri/ =404;
}

Когда использовать: Как основной обработчик для веб-сайта или приложения. В этом блоке обычно задают корневую директорию, индексные файлы и директиву try_files для корректной обработки путей.

Пример 2: Точное совпадение (Exact Match)

Блок с модификатором = имеет наивысший приоритет и активируется только при полном совпадении URI.

location = /favicon.ico {
    access_log off;
    log_not_found off;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Когда использовать: Для обработки конкретных, уникальных запросов — служебных файлов (/favicon.ico, /robots.txt), health-чек эндпоинтов (/health, /status) или специальных API-путей.

# Этот запрос СОВПАДЕТ с location = /favicon.ico
curl http://example.com/favicon.ico

# Эти запросы НЕ СОВПАДУТ (путь не идентичен)
curl http://example.com/favicon.ico/
curl http://example.com/favicon.ico?v=2

Пример 3: Префиксное совпадение для директории (Directory Prefix Match)

Префиксное совпадение без модификатора обрабатывает все запросы, URI которых начинаются с указанной строки.

location /images/ {
    root /var/www;
    expires 30d;
    add_header Cache-Control "public";
}

Поведение: Правило сработает для /images/, /images/logo.png, /images/photos/2024.jpg, но не для /images (без закрывающего слеша).

Разрешение пути: При использовании директивы root путь из location добавляется к значению root. Для запроса /images/logo.png и конфигурации выше итоговый путь к файлу будет: /var/www/images/logo.png.

Пример 4: Префиксное совпадение с остановкой (Prefix Match Stop)

Модификатор ^~ обеспечивает префиксное совпадение, но после успешного совпадения останавливает дальнейшую проверку regex-блоков.

location ^~ /images {
    root /var/www;
    expires 30d;
}

Преимущество в производительности: Исключение проверки регулярных выражений снижает нагрузку на CPU, что важно при высокой нагрузке на статические ресурсы.

Случай использования: Когда необходимо гарантировать, что запросы, начинающиеся с определённого префикса (например, /images), никогда не будут перехвачены другими regex-правилами в конфигурации.

Пример 5: Регистронезависимое регулярное выражение (Case-Insensitive Regex)

Модификатор ~* используется для совпадения по шаблону регулярного выражения без учёта регистра символов.

location ~* \.(jpg|jpeg|png|gif|ico|svg|webp)$ {
    root /var/www;
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

Что обрабатывает: Любой URI, который заканчивается на указанные расширения файлов, независимо от регистра: .jpg, .JPG, .Png, .SVG и т.д.

Внимание к производительности: Сопоставление по регулярным выражениям требует больше вычислительных ресурсов, чем префиксное. Для маршрутизации статических файлов с известными путями предпочтительнее использовать префиксные совпадения (^~). Regex следует применять для действительно сложных или гибких паттернов.

Пример 6: Регистрозависимое регулярное выражение (Case-Sensitive Regex)

Модификатор ~ активирует блок только при совпадении с регулярным выражением с учётом регистра.

location ~ /API/ {
    return 403;
    add_header Content-Type text/plain;
}

Что обрабатывает: Пути, содержащие /API/ в точном указанном регистре: /API/users, /API/v1/data. Пути /api/users или /Api/users совпадения не дадут.

Типичное применение: Блокировка запросов с некорректным регистром, обеспечение строгого соблюдения регистрочувствительных путей в API или обработка специфических паттернов, требующих точного соответствия.

Практические конфигурации для реальных задач

В этом разделе показаны законченные примеры конфигураций, решающих распространённые задачи: обслуживание статических файлов, настройка reverse proxy и организация структуры проекта.

Обслуживание статических файлов: root vs alias

Для отдачи статического контента используются две директивы: root и alias. Понимание их различий критически важно для предотвращения ошибок "404 Not Found".

Принцип работы root:

Директива root задаёт базовый каталог, к которому Nginx добавляет полный URI из запроса (включая путь из location).

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

• Запрос: /static/css/style.css
• Путь к файлу: /var/www/html/static/css/style.css
• Логика: root + location = /var/www/html + /static/css/style.css

Принцип работы alias:

Директива alias заменяет путь из location на указанный каталог. Это позволяет "сопоставить" URI с файловой структурой, не следующей той же иерархии.

location /static/ {
    alias /var/www/assets/;
}

• Запрос: /static/css/style.css
• Путь к файлу: /var/www/assets/css/style.css
• Логика: Часть /static/ в URI заменяется на /var/www/assets/.

Ключевые отличия и частые ошибки:

Правильный шаблон для alias: Всегда завершайте пути в location и alias слешем.

# Правильно
location /static/ {
    alias /var/www/assets/;
}

Пример: комплексная конфигурация для веб-приложения

Данный пример показывает типичную настройку для современного веб-приложения (например, SPA), где статика отделена от API, а все прочие запросы перенаправляются на основной файл приложения.

server {
    listen 80;
    server_name myapp.com;

    # Корневой каталог для статики
    root /var/www/myapp/public;

    # 1. Точное совпадение для служебных файлов
    location = /favicon.ico {
        access_log off;
        log_not_found off;
        expires max;
    }
    location = /robots.txt {
        access_log off;
        log_not_found off;
    }

    # 2. Префиксное совпадение для статических ресурсов
    location ^~ /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        # Пытаемся отдать файл, иначе возвращаем 404
        try_files $uri =404;
    }

    # 3. Обработка API-запросов через reverse proxy
    location /api/ {
        # Передача запроса backend-приложению
        proxy_pass http://backend_api:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # Отключаем кеширование для API по умолчанию
        proxy_cache off;
        add_header Cache-Control "no-store, no-cache, must-revalidate";
    }

    # 4. Обработка всех остальных запросов (SPA routing)
    location / {
        # Пробуем отдать существующий файл, иначе перенаправляем на index.html
        try_files $uri $uri/ /index.html;
    }

    # 5. Безопасность: запрет доступа к скрытым файлам
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
        return 404;
    }
}

Разбор логики:

1. /favicon.ico, /robots.txt — обрабатываются напрямую с оптимальными заголовками кеширования.
2. /assets/ — статические файлы (CSS, JS, изображения) отдаются с долгосрочным кешированием.
3. /api/ — все API-запросы перенаправляются на отдельный backend-сервис.
4. / — основное правило для SPA: если файл не найден, запрос перенаправляется на index.html для клиентского роутинга.
5. Скрытые файлы — доступ к файлам, начинающимся с точки (например, .git, .env), блокируется.

Пример: настройка reverse proxy и балансировки нагрузки

Директива location часто используется для маршрутизации трафика к различным backend-сервисам.

# Базовый upstream-блок для балансировки
upstream backend_servers {
    server 10.0.1.10:8080 weight=3; # Основной сервер с большим весом
    server 10.0.1.11:8080;          # Резервный сервер
    server 10.0.1.12:8080 backup;   # Сервер только для аварийных случаев
}

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

    # Маршрутизация основного приложения
    location /app/ {
        proxy_pass http://backend_servers/; # Важно: слеш в конце "срезает" /app/
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 5s;
    }

    # Отдельный эндпоинт для health-чеков
    location = /health {
        proxy_pass http://backend_servers/status;
        proxy_set_header Host $host;
        access_log off;
    }

    # Статика для админ-панели обслуживается локально
    location ^~ /admin/static/ {
        alias /var/www/admin-static/;
        expires 30d;
    }

    # Все запросы к /admin/ (кроме статики) идут на отдельный backend
    location /admin/ {
        proxy_pass http://admin_backend:9000;
        proxy_set_header Host $host;
    }
}

Отладка и оптимизация конфигурации

Создание правильной конфигурации — итеративный процесс. Этот раздел посвящён практическим методам проверки, анализа и улучшения работы блоков location.

Методы отладки и проверки

1. Валидация синтаксиса перед применением

   Любое изменение конфигурации должно начинаться с проверки синтаксиса. Это предотвратит падение сервера из-за опечатки.

   # Проверка синтаксиса конфигурационных файлов Nginx/Angie
   sudo nginx -t
   # Или, если используется Angie и бинарник назван иначе:
   sudo angie -t
   
   # В случае успеха вы увидите:
   # nginx: configuration file /etc/nginx/nginx.conf test is successful

2. Определение активного блока location для запроса

   Чтобы понять, какой именно блок обработал запрос, можно использовать несколько подходов:

   • Добавление уникальных заголовков: Самый наглядный способ при разработке.

     location /api/ {
         add_header X-Location-Matched "api_location" always;
         proxy_pass http://backend;
     }
     
     location ~* \.json$ {
         add_header X-Location-Matched "json_regex" always;
         # ...
     }

     Затем проверьте заголовки ответа через curl -I или вкладку Network в DevTools браузера.

   • Логирование в access_log: Используйте переменную $request_uri или создайте собственную для записи в лог.

     location /special/ {
         set $matched_location "special_prefix";
         access_log /var/log/nginx/debug.log combined;
         # ...
     }

3. Анализ ошибок через логи

   Логи — основной источник информации о проблемах.

   # Просмотр логов ошибок в реальном времени
   sudo tail -f /var/log/nginx/error.log
   
   # Поиск ошибок, связанных с конкретным server блоком или location
   sudo grep -r "location.*/api/" /var/log/nginx/

   • Частая ошибка open() failed (13: Permission denied): Убедитесь, что пользователь, от имени которого работает worker-процесс Nginx/Angie (часто www-data или nginx), имеет права на чтение файлов и обход директорий (x-права).
   • Ошибка primary script not found в FastCGI: Часто вызвана неверным указанием пути в директивах root или alias внутри location.

4. Использование переменной $request_uri для диагностики

   Эта переменная содержит исходный URI запроса (включая query string) и полезна для отладки сложных правил rewrite или try_files.

   location /debug/ {
       return 200 "Requested: $request_uri\nMatched: $uri\n";
       add_header Content-Type text/plain;
   }

Оптимизация производительности

1. Минимизация использования регулярных выражений (regex)

   Сопоставление по регулярным выражениям (~ и ~*) значительно дороже префиксного. Оптимизируйте по принципу:

   • Избегайте regex, если достаточно префикса. Для статических путей (/images/, /static/) всегда используйте location ^~.
   • Упорядочивайте regex от наиболее специфичного к наименее специфичному, так как проверка останавливается на первом совпадении.
   • Избегайте сложных regex с backtracking в часто используемых location.

   Сравнение подходов:

   # Менее оптимально: regex для статики
   location ~* \.(jpg|png|gif|css|js)$ { ... }
   
   # Оптимально: префикс для известных путей + простой regex для остального
   location ^~ /static/images/ { ... }
   location ^~ /static/css/ { ... }
   location ~* \.(jpg|png|gif)$ { ... } # Для изображений вне /static/

2. Эффективное кеширование статического контента

   Правильные заголовки кеширования разгружают сервер и ускоряют загрузку для пользователей.

   location ^~ /assets/ {
       root /var/www;
       # Долгосрочное кеширование для версионированных файлов (например, style.a1b2c3.css)
       location ~* \.[a-f0-9]{8,}\.(css|js|woff2)$ {
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
       # Стандартное кеширование для остальных файлов в /assets/
       expires 30d;
       add_header Cache-Control "public";
   }

3. Настройка кеширования прокси (Proxy Cache)

   Для динамического контента, который не меняется часто (каталог товаров, статьи), эффективно использовать кеш на стороне Nginx/Angie.

   # Определение зоны кеша (должно быть в контексте http {})
   proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m inactive=60m max_size=1g;
   
   server {
       location /api/catalog/ {
           proxy_pass http://backend;
           proxy_cache my_cache;           # Включение кеширования
           proxy_cache_key "$scheme$request_method$host$request_uri";
           proxy_cache_valid 200 302 5m;   # Кешировать успешные ответы 5 минут
           proxy_cache_valid 404 1m;       # Кешировать 404 на 1 минуту
           proxy_cache_use_stale error timeout updating;
   
           # Добавляем заголовок для отладки, говорящий, был ли ответ взят из кеша
           add_header X-Cache-Status $upstream_cache_status;
       }
   }

4. Оптимизация работы с файловой системой (sendfile, buffers)

   Для статических файлов добавьте в конфигурацию (обычно в контекст http {} или server {}):

   sendfile on;
   tcp_nopush on;
   # Оптимальный размер буферов для статики может зависеть от среднего размера файлов
   open_file_cache max=1000 inactive=20s;
   open_file_cache_valid 30s;
   open_file_cache_min_uses 2;
   open_file_cache_errors on;

FAQ: Распространённые вопросы о директиве location

location / {
    # Пробуем найти файл, затем директорию, иначе отдаём index.html
    try_files $uri $uri/ /index.html;
}

location /api/ {
    proxy_pass http://backend;
}
# Блок location / { ... } должен идти ПОСЛЕ

location ~ /\. {
    deny all; # Запрет доступа
    access_log off;   # Не логируем такие запросы
    log_not_found off;
    return 403; # или return 404;
}

location /api/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;          # Реальный IP в одном заголовке
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # Цепочка прокси в другом
    proxy_set_header X-Forwarded-Proto $scheme;       # Исходный протокол (http/https)
}

location /api/ {
    proxy_pass http://backend;
    status_zone api_location; # Angie соберёт метрики для этого блока
}

Заключение и выводы

Директива location — мощный и гибкий инструмент маршрутизации, образующий основу конфигурации веб-сервера. Правильное её понимание позволяет создавать эффективные, безопасные и простые в поддержке конфигурации.

Ключевые тезисы

1. Порядок выбора — основа предсказуемости. Nginx и Angie выбирают блок location не наугад, а по строгому алгоритму: сначала точное совпадение (=), затем самый длинный префикс с ^~ (остановка regex), потом регулярные выражения в порядке их объявления, и наконец — самый длинный префикс без ^~. Понимание этого порядка исключает неожиданности в маршрутизации.
2. Модификатор определяет поведение. Выбор между =, ^~, ~, ~* или отсутствием модификатора — это выбор между скоростью, точностью и гибкостью. Для статики используйте ^~, для уникальных эндпоинтов — =, а к регулярным выражениям прибегайте только когда без них нельзя обойтись.
3. root и alias — разные логики. root добавляет путь из location к своему значению, а alias заменяет его. Путаница между ними — частая причина ошибок 404. Запоминайте правило: alias должен заканчиваться слешем, если location им заканчивается.
4. Отладка и тестирование обязательны. Никогда не перезагружайте конфигурацию без nginx -t. Используйте уникальные заголовки, логи и переменные вроде $request_uri для понимания того, какой блок сработал. Мониторьте error.log.
5. Производительность можно настраивать. Минимизация regex, правильное кеширование статики (заголовки expires, Cache-Control), настройка кеша прокси (proxy_cache) и параметров работы с файловой системой (sendfile, буферы) — всё это напрямую влияет на скорость отклика сервера и его способность выдерживать нагрузку.

Сравнение с Angie: практический итог

С точки зрения директивы location, Angie является полностью совместимой заменой Nginx. Все рассмотренные синтаксис, модификаторы, алгоритмы и примеры конфигураций работают в Angie идентичным образом. Это позволяет переносить существующие конфигурации Nginx в Angie без изменений, обеспечивая простоту миграции.

Главное преимущество Angie в данном контексте — встроенные инструменты мониторинга и диагностики. Директива status_zone, позволяющая собирать детальные метрики Prometheus по каждому блоку location, превращает веб-сервер из "чёрного ящика" в понятный и наблюдаемый компонент инфраструктуры. Это особенно ценно в микросервисных средах и при тонкой настройке производительности.

Рекомендация

Лучший способ освоить location — практика. Создайте тестовый сервер или используйте sandbox-окружение, где можно безопасно экспериментировать с разными комбинациями блоков, наблюдая за результатом через curl и логи. Начните с простых префиксных правил, постепенно добавляя сложность (regex, вложенные location, прокси), всегда проверяя и документируя поведение.

Мастерство настройки location — это мастерство управления потоком запросов, которое лежит в основе работы быстрого и надёжного веб-приложения.