Как настроить gzip и Brotli в Nginx: пошаговая инструкция

За 20–30 минут вы настроите в Nginx сжатие HTML, CSS, JavaScript, JSON и SVG: сначала включите встроенный gzip, затем добавите Brotli, если модуль уже установлен или доступен в сборке. В конце проверите конфигурацию через nginx -t и убедитесь по заголовкам ответа, какой алгоритм получил браузер.

Что нужно подготовить

Примеры рассчитаны на Nginx 1.25+ в Linux. Директивы gzip входят в стандартный HTTP-модуль Nginx. Brotli в официальную поставку Nginx обычно не входит: для него нужен отдельный модуль, например ngx_brotli, либо пакет от вашего дистрибутива.

• SSH-доступ к серверу с правами на изменение конфигурации Nginx;
• домен или тестовый URL, который обслуживает этот Nginx;
• команда curl для проверки заголовков;
• резервная копия файла конфигурации перед изменениями;
• установленный модуль Brotli, если вы хотите использовать именно его.

Путь к конфигурации зависит от системы. Часто это /etc/nginx/nginx.conf, а отдельные сайты лежат в /etc/nginx/conf.d/ или /etc/nginx/sites-enabled/. Узнать, какие файлы реально подключены, можно командой nginx -T.

Шаг 1. Проверьте текущую конфигурацию

Сначала сохраните рабочий вариант и выведите итоговую конфигурацию. Так вы увидите не только основной файл, но и подключённые фрагменты.

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup
sudo nginx -T

Проверка результата: в выводе нет сообщений об ошибке, а команда завершается с кодом 0. Если путь к файлу отличается, замените его в команде резервного копирования.

Шаг 2. Включите gzip

Добавьте эти директивы внутрь блока http. Не помещайте их внутрь server, если хотите применить настройку ко всем сайтам на этом экземпляре Nginx.

http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 5;
    gzip_min_length 1000;

    gzip_types
        text/plain
        text/css
        text/xml
        application/xml
        application/json
        application/javascript
        application/wasm
        image/svg+xml;

    # Остальные директивы http, включая include и server, остаются здесь.
}

gzip_comp_level 5 — компромисс между размером ответа и нагрузкой на CPU. Уровень 9 не означает «в девять раз лучше»: он может заметно замедлить сжатие при небольшом выигрыше в размере.

Не добавляйте в gzip_types уже сжатые форматы вроде JPEG, PNG, WebP, MP4 и ZIP. Повторное сжатие почти не уменьшит файл, зато потратит процессор.

Проверка результата: выполните команду.

sudo nginx -t

В ответе должны появиться строки syntax is ok и test is successful. Если проверка прошла, примените настройку без остановки рабочих соединений.

sudo systemctl reload nginx

Проверка результата: запросите страницу с заголовком, который сообщает серверу о поддержке gzip.

curl -I -H 'Accept-Encoding: gzip' https://example.com/

Для сжимаемого ответа ищите Content-Encoding: gzip и обычно Vary: Accept-Encoding. Если ответ — редирект, ошибка или файл с неподходящим MIME-типом, заголовка сжатия может не быть.

Шаг 3. Проверьте доступность Brotli

Brotli не включается одной строкой в стандартном Nginx. Сначала проверьте итоговую конфигурацию и установленные модули.

sudo nginx -T 2>&1 | grep -i brotli

Проверка результата: в выводе есть директивы или упоминание Brotli. Пустой вывод означает, что модуль, вероятно, не подключён. Не вставляйте директивы brotli on; до установки модуля: Nginx завершит проверку с ошибкой «unknown directive».

Способ установки зависит от дистрибутива и способа сборки Nginx. Используйте пакетный менеджер или инструкцию сборки для вашей системы, а путь к динамическому модулю сверяйте с документацией пакета. Не копируйте случайный файл .so от другой версии Nginx: несовместимый модуль может не загрузиться после обновления сервера.

Gzip — безопасная базовая настройка, а Brotli — дополнительная возможность. Сначала добейтесь корректной работы gzip, затем подключайте второй модуль и проверяйте его отдельно.

Шаг 4. Добавьте Brotli, если модуль установлен

Ниже приведён блок для модуля ngx_brotli. Разместите его в том же контексте http, где находится настройка gzip.

http {
    brotli on;
    brotli_comp_level 5;
    brotli_min_length 1000;

    brotli_types
        text/plain
        text/css
        text/xml
        application/xml
        application/json
        application/javascript
        application/wasm
        image/svg+xml;

    # Остальные директивы http, включая server, остаются здесь.
}

Список MIME-типов здесь повторяет список для gzip. Nginx выбирает тип по заголовку Content-Type, а не по расширению файла. Поэтому неправильный MIME-тип на стороне приложения может отключить сжатие даже при корректной конфигурации.

Проверка результата: сначала снова проверьте синтаксис.

sudo nginx -t
sudo systemctl reload nginx

Обе команды должны завершиться без ошибки. Затем отправьте запрос с поддержкой Brotli.

curl -I -H 'Accept-Encoding: br' https://example.com/

Для подходящего ответа должна появиться строка Content-Encoding: br. Если сервер отвечает gzip, проверьте, что модуль Brotli действительно загружен, а запрос не проходит через прокси или CDN, который меняет заголовки.

Шаг 5. Проверьте выбор алгоритма

Браузер может сообщить сразу о нескольких поддерживаемых алгоритмах. Обычно сервер выбирает Brotli, если он доступен, но фактический результат нужно проверять заголовками.

curl -s -D - -o /dev/null -H 'Accept-Encoding: br, gzip' https://example.com/
curl -s -D - -o /dev/null -H 'Accept-Encoding: gzip' https://example.com/
curl -s -D - -o /dev/null -H 'Accept-Encoding: identity' https://example.com/

Проверка результата: в первом запросе ожидайте Content-Encoding: br, во втором — Content-Encoding: gzip, а в третьем — отсутствие сжатия. Реальный результат может отличаться для короткого ответа: директивы gzip_min_length и brotli_min_length намеренно пропускают небольшие файлы.

Если не получилось

«unknown directive brotli»

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

«module is not binary compatible»

Динамический модуль собран для другой версии или другой сборки Nginx. Используйте пакет, собранный для текущего бинарного файла, либо пересоберите модуль; проверка nginx -V покажет параметры сборки.

В ответе нет Content-Encoding

Проверьте MIME-тип, размер ответа, наличие заголовка Content-Encoding на промежуточном прокси и фактический файл конфигурации через nginx -T. Для gzip также убедитесь, что директива gzip on находится в активном контексте.

После изменения появился HTTP 500 или Nginx не перезагружается

Не перезапускайте сервис повторно вслепую. Выполните sudo nginx -t, исправьте строку, указанную в сообщении, и только после успешной проверки повторите reload. Если конфигурация сломана, верните резервную копию и снова проверьте её.

Термин: Vary

Vary: Accept-Encoding — заголовок, который сообщает кешам: ответ зависит от того, какой алгоритм сжатия поддерживает клиент. Без него прокси теоретически может отдать одному клиенту закешированный gzip-ответ, не учитывая его возможности.

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

После настройки измерьте не только размер файла, но и время ответа под реальной нагрузкой. Посмотрите на загрузку CPU, долю ответов с кодами 4xx и 5xx, работу CDN и заголовки кеширования. Если статические файлы собираются заранее, отдельная задача — предварительно создавать версии .br и .gz и раздавать их через brotli_static или gzip_static; это уменьшает нагрузку на CPU, но требует отдельной настройки сборки и деплоя.

Обновляйте Nginx и модуль Brotli вместе. После каждого обновления повторяйте nginx -t и проверку через curl: сжатие легко «сломать» изменением MIME-типа, прокси или структуры подключаемых конфигураций.