Как проверить конфигурацию Nginx: nginx -t, nginx -T и разбор типичных ошибок | AdminWiki

Как проверить конфигурацию Nginx: nginx -t, nginx -T и разбор типичных ошибок

08 ноября 2026 13 мин. чтения

Проверить конфигурацию Nginx перед перезагрузкой можно двумя командами: nginx -t тестирует синтаксис и доступность файлов, nginx -T делает то же самое и дополнительно печатает в stdout итоговую конфигурацию со всеми подключёнными include. Первая отвечает на вопрос "конфиг валиден?", вторая показывает, что именно применится после reload.

Рабочий порядок на проде такой: сохранить текущую конфигурацию, прогнать nginx -t от правильного пользователя и с явными путями, снять nginx -T и сравнить с предыдущим снимком, разобрать сообщения [emerg] и [warn], выполнить reload, проверить статус, логи и ответы по ключевым доменам. Ниже разбираем каждый шаг с командами и типичными ошибками из вывода.

Главное ограничение запомните сразу: успешный тест подтверждает только то, что Nginx смог прочитать и разобрать конфиг. Работающий сервис зависит ещё от бэкендов, сертификатов, портов, DNS и прав пользователя, под которым крутятся worker-процессы.

Зачем проверять конфигурацию Nginx перед перезагрузкой

Nginx не применит конфигурацию, которая не прошла синтаксическую проверку: reload завершится ошибкой, а сервис продолжит работать на прежней версии конфига. Проверка занимает секунды. Разбор последствий неудачного restart на проде занимает минуты или часы, если поднимать сервис приходится вручную.

Разница между reload и restart критична. При reload (сигнал HUP) master-процесс сначала проверяет корректность синтаксиса конфигурации, затем запускает новые worker-процессы с новой конфигурацией и плавно завершает старые: они переходят в состояние "is shutting down", дорабатывают запросы и через некоторое время завершаются, после чего запросы обрабатывают только новые worker-процессы. Соединения при этом не рвутся. При restart сервис останавливается полностью, поэтому ошибка в конфиге означает простой до отката правок. Именно поэтому проверка идёт до команды перезагрузки, а не после.

Второй риск - правки, которые формально валидны, но меняют поведение: перекрытый location, забытый include, директива в чужом контексте, дубль виртуального хоста. Синтаксис чистый, тест зелёный, а после reload часть запросов уходит не туда. От этого спасает только nginx -T с последующей сверкой итоговой конфигурации.

Механику graceful shutdown и то, как reload применяет новую конфигурацию без обрыва соединений, разбираем отдельно: как работает nginx -s reload и как встроить его в CI/CD.

nginx -t: базовая проверка синтаксиса и как читать вывод

Команда не меняет состояние работающего сервиса и безопасна на проде. Запускайте её так:

sudo nginx -t
sudo nginx -t; echo "exit code: $?"

Успешный вывод выглядит предсказуемо:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

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

nginx: [emerg] unknown directive "proxy_set_heder" in /etc/nginx/sites-enabled/app.conf:42
nginx: configuration file /etc/nginx/nginx.conf test failed

Формат читается так: уровень в квадратных скобках, что именно не так, файл и строка. Начинайте разбор с файла и строки, а не с текста сообщения. Exit code 0 означает успех, ненулевой код - ошибку, поэтому в скриптах и CI проверяйте именно код возврата, а не наличие слова "successful" в выводе.

Уровень [emerg] блокирует загрузку конфигурации. Уровень [warn] не мешает запуску, но сигнализирует о проблеме: конфликтующие server_name, переопределённые параметры протокола, устаревшая директива. Предупреждения стоит разбирать до reload, иначе они превращаются в источник странных ошибок в логах.

Что именно проверяет nginx -t, а что нет

Границы проверки проще держать перед глазами в виде таблицы.

ПроверяетНе проверяет
Синтаксис директив и допустимость контекстаДоступность upstream и бэкендов
Число аргументов у директивСрок действия и полноту цепочки сертификата
Читаемость include-файловЗанятость портов другими процессами
Читаемость файлов ключей и сертификатовПрава пользователя worker на статику и логи
Корректность значений: числа, размеры, IP-адресаРезолв DNS-имён в момент запроса
Наличие файлов путей из директив на момент тестаПоведение приложения и таймауты

Поясним строку про сертификаты. При тесте nginx пытается открыть файлы, на которые ссылается конфигурация, а приватный ключ должен быть доступен для чтения master-процессу. То есть успешный nginx -t подтверждает читаемость ключа и сертификата, но не проверяет срок действия и полноту цепочки: в объединённом файле сертификат сервера должен идти перед промежуточными, а отправку полной цепочки проверяют отдельно утилитой openssl s_client. Набор проверок зависит от версии Nginx и собранных модулей. Список модулей и путь к конфигу по умолчанию смотрите в выводе nginx -V, а поведение конкретных директив сверяйте с документацией своей версии.

Официальное описание ключей -t, -T и -q приведено в документации Nginx: Command-line parameters. Требования к хранению ключа и порядку сертификатов в файле описаны в разделе Configuring HTTPS servers.

Как запускать nginx -t от нужного пользователя

Тест под root проходит там, где рабочий процесс потом получит permission denied: root читает всё, а worker-процессы работают под www-data, nginx или отдельным сервисным пользователем. Сначала выясните, кто именно запускает процессы:

ps -o user=,pid=,cmd= -C nginx
systemctl show nginx -p User -p Group
whoami

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

sudo -u www-data test -r /etc/nginx/ssl/example.key && echo readable
sudo -u www-data test -x /var/www/site && echo traversable

Запускать тест только от лица worker-пользователя тоже неверно: он не прочитает приватный ключ, который доступен лишь root, и вы получите ложную ошибку. Практика такая: тестируйте от root с явным указанием -c и -p, а права worker-пользователя проверяйте отдельными командами test -r и test -x по статике, логам и сокетам.

nginx -T: как вывести итоговую собранную конфигурацию

Ключ -T проверяет конфигурационный файл и дополнительно выводит конфигурационные файлы в стандартный вывод; опция появилась в версии 1.9.2. Перед каждым файлом идёт комментарий с его путём, поэтому видно, из какого include пришёл конкретный server или location:

# configuration file /etc/nginx/nginx.conf:
# configuration file /etc/nginx/conf.d/app.conf:
# configuration file /etc/nginx/sites-enabled/site.conf:

Вывод большой, поэтому сохраняйте его в файл и снимайте снимки до и после правок:

sudo nginx -T > /tmp/nginx-full-$(date +%F-%H%M).conf
sudo nginx -T > /tmp/nginx-new.conf
diff -u /tmp/nginx-full-2026-11-01-1200.conf /tmp/nginx-new.conf

Diff по итоговой конфигурации показывает реальные изменения, включая те, что пришли из подключённых файлов. Это ловит две частые ситуации: include не подхватился, потому что файл лежит не в sites-enabled, и правка сделана в файле, который перекрывается другим include. Флаг -q подавляет не связанные с ошибками сообщения при проверке конфигурации, это удобно в скриптах.

Как найти нужный блок в выводе nginx -T

Ищите по server_name или пути location, выводя контекст вокруг найденной строки:

sudo nginx -T | grep -n 'server_name example.com'
sudo nginx -T | grep -n -B3 'location /api/'
sudo nginx -T | grep -c 'location '

Если нужного server_name в выводе нет, значит файл не подключён, и никакие правки в нём не действуют. Если блок есть дважды, вы нашли источник конфликта. Алгоритм отладки маршрутизации, приоритетов location и proxy_pass разбираем в материале отладка маршрутизации Nginx: логи, проверка location и типичные ошибки.

Явное указание -c и -p: когда это обязательно

-c задаёт путь к главному конфигу, -p задаёт prefix, от которого разрешаются относительные пути внутри конфигурации. Значения по умолчанию зашиты при сборке, их видно в nginx -V:

nginx -V 2>&1 | tr ' ' '\n' | grep -E 'prefix|conf-path'
sudo nginx -t -c /etc/nginx/nginx.conf -p /etc/nginx/
sudo nginx -T -c /opt/nginx/conf/nginx.conf -p /opt/nginx/

Явные пути обязательны в четырёх случаях: нестандартная установка из исходников, запуск в контейнере с другим prefix, несколько инстансов Nginx на одной машине и проверка конфига до деплоя на сервер. Без -p относительные пути вроде include conf.d/*.conf или logs/error.log разрешаются от другого каталога, и проверка покажет не тот результат, который получится после reload.

Типичные ошибки из вывода nginx -t и как их исправить

В каждом сообщении есть файл и строка: nginx: [emerg] текст in файл:строка. Начинайте с них. Сводка частых сообщений:

СообщениеПричинаЧто делать
unexpected end of fileНезакрытый блок, кавычка или пропущенная точка с запятойПроверить баланс фигурных скобок и ; в указанном файле, смотреть на 10-20 строк выше
unknown directiveОпечатка, модуль не собран или не загружен, директива вне своего контекстаСверить имя директивы с документацией версии, проверить nginx -V и контекст
invalid number of argumentsЛишний или пропущенный аргумент, кавычки склеили или разорвали строкуСверить сигнатуру директивы и расставить кавычки
duplicate locationДва одинаковых location в одном server, двойной includeНайти дубль через nginx -T, убрать повтор

unexpected end of file

Сообщение выглядит так: nginx: [emerg] unexpected end of file, expecting "}" in /etc/nginx/conf.d/app.conf:87. Nginx дошёл до конца файла и не нашёл закрывающую скобку. Строка 87 часто оказывается последней строкой файла, а реальная ошибка расположена выше.

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

grep -c '{' /etc/nginx/conf.d/app.conf
grep -c '}' /etc/nginx/conf.d/app.conf

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

unknown directive

Пример: nginx: [emerg] unknown directive "proxy_set_heder" in /etc/nginx/sites-enabled/app.conf:42. Причина первая и самая частая - опечатка в имени директивы. Вторая - директива принадлежит модулю, который не собран в вашем бинарнике. Третья - директива стоит в неподходящем контексте, например используется там, где её не бывает.

nginx -V 2>&1 | tr ' ' '\n' | grep with-
nginx -V 2>&1 | grep -o 'with-[a-z0-9_]*module' | sort -u

Список с with- показывает, какие модули включены при сборке. Если нужного модуля нет, директива не появится ни при какой правке текста. Отдельный случай - конфиг, перенесённый со старого сервера: в nginx 1.25.1 параметр http2 в директиве listen объявлен устаревшим, вместо него следует использовать отдельную директиву http2. Устаревание не ломает работу сразу: nginx выдаёт предупреждение вида "the listen ... http2 directive is deprecated, use the http2 directive instead", и конфиг продолжает работать. Сверяйте такие места с документацией именно своей версии.

invalid number of arguments

Пример: nginx: [emerg] invalid number of arguments in "root" directive in /etc/nginx/conf.d/site.conf:12. Директива получила не то количество аргументов, которое ожидает. Типичные причины: путь с пробелом без кавычек превратился в два аргумента, лишний параметр после значения, пропущенный обязательный аргумент.

root /var/www/my site;   # ошибка: два аргумента
root "/var/www/my site"; # корректно

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

duplicate location

Пример: nginx: [emerg] duplicate location "/api/" in /etc/nginx/sites-enabled/api.conf:8. В одном server-блоке оказались два location с одинаковым префиксом. Классика: файл сайта лежит в sites-available, на него сделан симлинк в sites-enabled, и при этом тот же файл дополнительно подключён через include в conf.d.

sudo nginx -T | grep -n 'location "/api/"'
ls -l /etc/nginx/sites-enabled/
readlink -f /etc/nginx/sites-enabled/*.conf

Первая команда покажет все вхождения и файлы, откуда они пришли. Дальше ищите двойное подключение: симлинк и оригинал, два include одного каталога, копию конфига с другим именем. Уберите повтор и повторите тест.

Проблемы с правами и отсутствующими include-файлами

Часть ошибок не связана с синтаксисом. Nginx не может открыть файл и сообщает об этом отдельным кодом в скобках.

nginx: [emerg] open() "/etc/nginx/ssl/example.key" failed (13: Permission denied)
nginx: [emerg] open() "/etc/nginx/sites-enabled/old-site.conf" failed (2: No such file or directory)

Код 13 означает запрет доступа, код 2 - отсутствие файла. Для прав используйте namei, она показывает права на каждом уровне пути, а не только на конечном файле:

namei -l /etc/nginx/ssl/example.key
ls -l /etc/nginx/ssl/example.key

Рабочая схема: приватный ключ 600 и владелец root:root, каталоги 755 с битом x для всех, конфиги 644. Если на пути к файлу есть каталог без права выполнения, Nginx не откроет файл даже с правами 777 на сам файл. В дистрибутивах с SELinux проверьте контекст и политику:

getenforce
ls -Z /etc/nginx/ssl/example.key
restorecon -Rv /etc/nginx

Для AppArmor смотрите aa-status и профили в /etc/apparmor.d/. Часть таких ошибок проявляется уже после reload, в виде 403 на статике: разбор этих сценариев есть в материале раздача статики через Nginx: права, симлинки, SELinux и коды 403/404.

Отсутствующий include выглядит как код 2 при открытии файла. Самая частая причина - висячий симлинк в sites-enabled после удаления файла сайта. Проверяйте так:

ls -l /etc/nginx/sites-enabled/
readlink -f /etc/nginx/sites-enabled/old-site.conf
find /etc/nginx -xtype l

find с ключом -xtype l покажет все битые симлинки. Отдельно стоит помнить, что include с маской (например, conf.d/*.conf) и include с прямым указанием файла - не одно и то же: при маске в выборку попадают только реально существующие совпадения, а прямой путь к несуществующему файлу даёт ошибку открытия. Поведение с симлинками и масками зависит от версии, поэтому проверяйте на своей сборке. Логика доступа к файлам и каталогам подробно разобрана в статье права доступа к данным в Nginx: аутентификация и контроль.

Почему успешный nginx -t не гарантирует корректную работу сервиса

Тест проверяет текст конфигурации и доступность файлов. Сервис же зависит от сети, процессов и окружения. Что остаётся вне проверки:

  • доступность upstream: бэкенд может лежать, и вы получите 502 при полностью валидном конфиге;
  • срок действия и цепочка сертификата: просроченный сертификат загружается без ошибок;
  • занятость портов: конфликт с другим процессом выяснится только при reload или старте;
  • права worker-пользователя на статику, логи и unix-сокеты;
  • DNS-имена upstream, которые резолвятся при загрузке конфигурации;
  • поведение приложения, таймауты и лимиты соединений.

Что проверить после успешного nginx -t

  1. Итоговая конфигурация. sudo nginx -T > /tmp/nginx-new.conf и diff с прошлым снимком. Показывает, что реально изменилось.
  2. Reload вместо restart. sudo systemctl reload nginx. Соединения не рвутся, старые worker-процессы дорабатывают запросы.
  3. Статус сервиса. systemctl status nginx --no-pager и journalctl -u nginx -n 50 --no-pager. Ловит неудачный reload и падение worker-процессов.
  4. Логи ошибок. tail -n 50 /var/log/nginx/error.log. Смотрите [emerg] и [alert] за последние минуты.
  5. Ответы по доменам. curl -I https://example.com и curl -s -o /dev/null -w '%{http_code}\n' https://example.com. Проверяет коды 200/301/403/502 по факту.
  6. Сертификат. openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject. Показывает даты действия и CN.
  7. Бэкенд. curl -I http://127.0.0.1:8080/health напрямую, минуя Nginx. Отделяет проблему приложения от проблемы проксирования.

Пункты 2 и 3 связаны с механикой применения конфигурации, детали и сценарий быстрого отката описаны в руководстве по безопасному обновлению конфигурации Nginx через reload. Как именно master-процесс обрабатывает сигнал HUP и завершает старые worker-процессы, описано в документации Controlling nginx.

Чек-лист проверки конфигурации Nginx перед перезагрузкой на проде

Список рассчитан на применение прямо сейчас, по шагам, без пропусков.

  1. Бэкап конфигурации. tar -czf /root/nginx-$(date +%F-%H%M).tar.gz /etc/nginx. Без копии откат превращается в ручное восстановление по памяти. Готовые сценарии бэкапа и восстановления за 5 минут есть в чек-листе по бэкапу и восстановлению Nginx.
  2. Пользователь и контекст. ps -o user=,pid=,cmd= -C nginx и systemctl show nginx -p User -p Group. Определяет, под кем работают worker-процессы и чьи права проверять.
  3. Тест с явными путями. sudo nginx -t -c /etc/nginx/nginx.conf -p /etc/nginx/; echo $?. Ноль в конце обязателен, иначе дальше идти нельзя.
  4. Снимок итоговой конфигурации. sudo nginx -T > /tmp/nginx-new.conf плюс diff с предыдущим снимком. Показывает, что именно применится после reload.
  5. Include и дубли. grep по server_name и location в выводе -T, ls -l /etc/nginx/sites-enabled/, find /etc/nginx -xtype l. Ловит неподключённые файлы, висячие симлинки и двойные location.
  6. Права на ключи, конфиги и статику. namei -l по ключевым путям, sudo -u www-data test -r по файлам статики. Закрывает ошибки, которые тест под root не видит.
  7. Reload вместо restart. sudo systemctl reload nginx. Приложение не простаивает, соединения не обрываются.
  8. Статус и логи. systemctl status nginx, journalctl -u nginx -n 50, tail -n 50 /var/log/nginx/error.log. Подтверждает, что новые worker-процессы поднялись без ошибок.
  9. Проверка ответов. curl -I по ключевым доменам и эндпоинтам, openssl s_client по сертификату, curl к upstream напрямую. Подтверждает, что сервис отвечает нужными кодами и отдаёт действующий сертификат.
  10. План отката. знать путь к архиву, команду восстановления и что откатывать: распаковать /etc/nginx из архива, выполнить nginx -t, затем reload. План фиксируется до начала работ, а не в момент инцидента.

Прогоняйте этот список перед каждым изменением в /etc/nginx, включая правку одной директивы. Проверка занимает пару минут, а откат без бэкапа и без снимка nginx -T обычно растягивается на весь вечер.

Поделиться: