Gzip и Brotli в Nginx: частые ошибки новичков

Неправильная настройка gzip и Brotli может увеличить время загрузки даже при включённом сжатии: Nginx будет пропускать JSON, SVG или CSS из-за неверного MIME-типа, а директива Brotli остановит запуск сервера, если модуль не установлен. Ниже — практическая настройка для Nginx 1.26.x: от проверки модулей до теста заголовка Content-Encoding. Обычно работа занимает 15–30 минут.

Что нужно проверить до начала

Инструкция рассчитана на Linux-сервер с Nginx 1.26.x и доступом к конфигурации от имени root или пользователя, которому разрешён перезапуск сервиса. Команды могут отличаться для Debian, Ubuntu, RHEL и контейнеров, но сами директивы относятся к Nginx 1.26.x.

• Есть SSH-доступ к серверу.
• Вы знаете, где лежит активная конфигурация сайта.
• В системе установлен curl.
• Для gzip достаточно стандартной сборки Nginx.
• Для Brotli нужен отдельный модуль, например ngx_brotli. В официальную сборку Nginx Open Source он обычно не входит.

Сначала посмотрите версию и собранные модули:

nginx -v
nginx -V 2>&1
nginx -T > /tmp/nginx-config.txt

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

Шаг 1. Проверьте Brotli-модуль

Gzip можно включить почти в любой стандартной сборке. Для Brotli сначала проверьте, доступен ли модуль в виде динамического модуля или он был встроен при сборке. В выводе nginx -V ищите параметры сборки и подключение модулей. Одного наличия библиотеки Brotli в системе недостаточно: Nginx должен знать директивы brotli и brotli_types.

Проверка успешна, если тест конфигурации понимает директиву Brotli. Не добавляйте настройки ниже вслепую: при отсутствии модуля получите ошибку unknown directive "brotli". В таком случае установите пакет модуля из репозитория вашей операционной системы либо соберите динамический модуль по документации проекта ngx_brotli. Способ установки зависит от дистрибутива и способа установки Nginx.

Шаг 2. Добавьте настройки gzip и Brotli

Директивы сжатия поместите внутрь блока http. На Debian и Ubuntu файл в /etc/nginx/conf.d/ обычно подключается из http, но это нужно проверить в /etc/nginx/nginx.conf. Не вставляйте этот фрагмент внутрь другого блока server, если выбранный контекст не разрешён документацией.

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 5;
gzip_min_length 1000;
gzip_types
    text/plain
    text/css
    text/xml
    text/javascript
    application/javascript
    application/json
    application/xml
    application/rss+xml
    application/atom+xml
    image/svg+xml;

brotli on;
brotli_comp_level 5;
brotli_min_length 1000;
brotli_types
    text/plain
    text/css
    text/xml
    text/javascript
    application/javascript
    application/json
    application/xml
    application/rss+xml
    application/atom+xml
    image/svg+xml;

Параметр gzip_comp_level и его аналог для Brotli определяют баланс между нагрузкой на CPU и размером ответа. Уровень 5 — не универсальный рекорд, а безопасная отправная точка. Повышение уровня не гарантирует пропорционального уменьшения файла.

Проверка успешна, если файл сохранён, а команда ниже не сообщает об ошибках:

nginx -t

После этого примените конфигурацию без остановки активных соединений:

systemctl reload nginx

Проверка успешна, если команда завершается без ошибки, а сайт продолжает открываться. Если nginx -t не прошёл, reload выполнять нельзя.

Сжатие включается не для расширения файла, а для MIME-типа ответа. Файл data.json может сжиматься, а ответ с тем же содержимым и типом text/plain — уже по другой причине или с другими настройками.

Шаг 3. Проверьте, что браузер действительно получает сжатый ответ

Запрос без заголовка Accept-Encoding не показывает результат настройки: клиент как бы сообщает серверу, что сжатые варианты ему не нужны. Передайте поддерживаемые алгоритмы вручную и проверьте заголовки.

curl -I -H 'Accept-Encoding: br, gzip' https://example.com/app.css
curl -I -H 'Accept-Encoding: gzip' https://example.com/app.css

Замените https://example.com/app.css на URL существующего CSS, JavaScript, JSON или SVG-файла. В первом ответе обычно ожидается Content-Encoding: br, если модуль Brotli активен и ответ подходит под правила. Во втором — Content-Encoding: gzip. Заголовок Vary: Accept-Encoding нужен, чтобы кеш не выдал клиенту Brotli-версию, которую он не умеет распаковать.

Если файл меньше 1000 байт, сжатия может не быть из-за gzip_min_length и brotli_min_length. Это нормально: служебные заголовки и стоимость сжатия иногда делают маленький ответ больше.

Шаг 4. Проверьте MIME-типы

Директива gzip_types и brotli_types сопоставляет настройки с заголовком Content-Type, а не с окончанием URL. Посмотрите полный ответ:

curl -sI -H 'Accept-Encoding: br, gzip' https://example.com/api/data

Если API возвращает Content-Type: application/json, он попадает в приведённый список. Если сервер отдаёт CSS как application/octet-stream, добавлять случайные типы в конфигурацию — плохое решение. Сначала исправьте MIME-тип в приложении, upstream или настройках Nginx.

Проверка успешна, если тип ответа соответствует содержимому, а выбранный алгоритм появляется только у достаточно крупного ответа.

Частые ошибки новичков

Добавить Brotli без модуля

Ошибка unknown directive "brotli" означает, что активная сборка Nginx не знает такую директиву. Установка пакета brotli для командной строки не решает проблему автоматически. Нужен именно модуль Nginx, подключённый к той версии, которую запускает systemd.

Проверять только расширение файла

Расширение .js не гарантирует тип application/javascript. Проверяйте реальный HTTP-ответ через curl -I или вкладку Network в браузере. Если MIME-тип неверен, исправляйте источник заголовка.

Сжать изображения и архивы

JPEG, PNG, WebP, ZIP и MP4 уже используют собственные форматы сжатия. Добавление их в списки типов увеличивает нагрузку на CPU и почти не уменьшает размер. Сосредоточьтесь на текстовых ответах: HTML, CSS, JavaScript, JSON, XML и SVG.

Поднять уровень до максимума

Высокий уровень сжатия может заметно увеличить время ответа и загрузку CPU. Особенно это проявляется на сервере, где приложение и Nginx конкурируют за те же ядра. Сравнивайте размер ответа и время формирования на реальном трафике, а не только на одном локальном файле.

Изменить конфигурацию и не проверить её

Синтаксическая ошибка или директива не в том контексте может привести к отказу reload. Правильный порядок: сохранить резервную копию, выполнить nginx -t, затем сделать systemctl reload nginx и снова проверить HTTP-заголовки.

Где эта настройка ломается

Сжатие может исчезнуть после добавления CDN, reverse proxy или кеша перед Nginx. В таком случае браузер видит ответ не от origin-сервера, а от промежуточного узла. Проверьте заголовки на публичном URL и отдельно на origin, если у вас есть доступ.

Ещё один граничный случай — уже сжатый ответ от приложения. Повторное сжатие не всегда полезно и может быть отключено промежуточным слоем. Также не смешивайте динамическое сжатие с готовыми файлами .br и .gz: раздача предварительно сжатых файлов требует отдельной настройки и отдельной проверки кешей.

Если Brotli нужен только для статических файлов, а модуль нельзя установить, оставьте рабочий gzip и настройте сборку фронтенда на генерацию заранее сжатых ресурсов. Это другой сценарий, поэтому его не стоит добавлять в тот же конфигурационный фрагмент без проверки цепочки раздачи.

Что делать дальше

Снимите базовые показатели до и после настройки: размер HTML, CSS, JavaScript и JSON, время ответа и загрузку CPU Nginx. Проверяйте несколько размеров файлов и оба заголовка Accept-Encoding. В продакшене отдельно контролируйте кеш CDN и наличие Vary: Accept-Encoding. Если после включения Brotli выросло время ответа, сначала верните уровень 5 или ниже и сравните результат на реальном наборе URL, а не на одной странице.

Термин: MIME-тип — HTTP-метка, описывающая формат содержимого ответа, например text/css для таблицы стилей или application/json для JSON. Nginx использует её при выборе типов, которые нужно сжимать.