Самые распространенные ошибки синтаксиса Nginx

LEMP Stack | Amber | Комментировать запись

Nginx — это популярный веб-сервер, на котором размещаются многие крупные сайты. При настройке веб-сервера Nginx обычно создается domain block с деталями конфигурации, чтобы сайт мог обрабатывать входящие запросы. Часто при настройке Nginx в файле конфигурации допускают ошибки. Мы разберем самые распространенные синтаксические ошибки, а также подумаем, как их проверить и как исправить.

Примеры в этом мануале были протестированы на сервере Ubuntu, но они будут работать на большинстве установок Nginx, так как они в основном связаны со стандартным файлом конфигурации. Каталоги и пути могут немного отличаться.

Проверка лога ошибок Nginx

В этом мануале мы рассмотрим самые распространенные ошибки и способы их устранения. Синтаксические ошибки нарушают структуру, которую Nginx распознает как допустимую. Часто одна ошибка переходит в другую и становится причиной более серьезной или отдельной проблемы. Поэтому конкретные обстоятельства и настройки в реальной среде могут отличаться от тех, что приведены в данном мануале.

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

sudo cat /var/log/nginx/error.log

В этом мануале позже будет рассказано, как разобрать и понять сообщения об ошибках Nginx.

Проверка файла конфигурации на наличие ошибок

Давайте посмотрим на пример domain block в Nginx с разными ошибками в файле конфигурации. Эти ошибки сделаны намеренно, чтобы показать вам, как их можно исправить. Чтобы проверить, есть ли в настройке какие-либо синтаксические ошибки, запустите следующую команду:

sudo nginx -t

Если ошибок нет, вывод будет следующим:

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

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

Выявление структурных синтаксических ошибок

Одна из распространенных ошибок при работе с Nginx – отсутствие необходимых символов или неправильная структура синтаксиса. Конфигурационный файл Nginx ориентирован на директивы, и эти директивы должны быть объявлены определенным образом. В противном случае конфигурационный файл будет структурно некорректным.

Директивы можно разделить на два типа, каждый из которых имеет свой синтаксис: простые директивы (которые содержат имя и параметры, заканчивающиеся точкой с запятой) и блочные директивы (разделяются фигурными скобками { } и могут содержать другие блоки внутри себя).

Если директива структурирована неправильно, Nginx не сможет распознать ее, что может привести к следующим ошибкам.

Ошибка Invalid parameter

Файл конфигурации Nginx очень требователен к структуре и синтаксису. Одна из самых частых проблем с синтаксисом связана с точкой с запятой. Например, рассмотрим такое сообщение об ошибке:

[emerg] invalid parameter "root" in /etc/nginx/sites-enabled/your_domain:5
nginx: configuration file /etc/nginx/nginx.conf test failed

Прежде чем решать эту проблему, нужно понять сообщение об ошибке Nginx. В нем есть подсказки, которые помогают определить причину ошибки. В этом случае [emerg] означает “emergency” — это связано с нестабильностью системы. Значит, Nginx столкнулся с проблемой, которая не позволяет ему работать.

Это сообщение об ошибке дополнительно указывает место, где обнаружена ошибка. Имейте в виду, что в настройках Nginx у вас будет свой файл конфигурации, связанный симликом с /etc/nginx/nginx.conf. Если вы следовали мануалу Установка Nginx в Ubuntu 20.04, то в пункте 5 вы видели, как это делается. Указана точная строка в конфигурационном файле с ошибкой: /etc/nginx/sites-enabled/your_domain:5. Также в этом файле есть invalid parameter “root”.

Теперь, когда у вас есть информация, где искать ошибку, вы можете открыть файл в любом текстовом редакторе. Мы будем работать с nano:

sudo nano /etc/nginx/sites-available/your_domain

Примечание: Все конфигурационные файлы можно найти в каталоге /etc/nginx/. 

Внутри файла найдите строку 5, на которую ссылается сообщение об ошибке:

server {
        listen 80;
        listen [::]:80;

       root /var/www/your_domain/html
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

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

Ошибка может быть не совсем очевидна. Напоминаем, из сообщения об ошибке следует, что проблема заключается в invalid parameter. Параметры — это аргументы, которые предоставляются директивам Nginx. В этом сценарии /var/www/your_domain/html – и есть это недействительный параметр. Он не работает потому, что в синтаксической структуре отсутствует символ, в данном случае – точка с запятой в конце строки.

Многие строки в этом файле также заканчиваются точкой с запятой. Точка с запятой должна стоять в конце каждой строки, которая содержит директиву. В этом примере у нас присутствует директива root, которая указывает на root каталог, который будет использоваться при поиске файла. Наличие root необходимо для того, чтобы Nginx мог найти определенный URL. Разберем важность директив в следующем разделе.

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

…

       root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

…

После исправления сохраните и закройте файл. 

Чтобы убедиться, что синтаксическая ошибка исправлена, выполните команду sudo nginx -t.

Неправильно поставленные фигурные скобки

Еще одна распространенная ошибка, которая может возникнуть в синтаксической структуре Nginx, связана с фигурными скобками { }. В отличие от предыдущей ошибки, в которой не было указано, как исправить недопустимый параметр, это сообщение указывает на ее причину:

nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/your_domain:15
nginx: configuration file /etc/nginx/nginx.conf test failed

Сообщение об ошибке указывает на строку 15, в которой содержится лишняя фигурная скобка в том же файле конфигурации, что и раньше. Откройте этот файл через текстовый редактор:

server {
        listen 80;
        listen [::]:80;

       root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

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

Внизу файла вы найдете фигурную скобку }. Сначала суть проблемы может быть непонятна, поскольку фигурная скобка вроде бы присутствует на своем месте. Однако при детальном разборе оказывается, что после этой фигурной скобки не хватает еще одной скобки. Правильное количество фигурных скобок в файле конфигурации Nginx очень важно, поскольку они указывают на открытие и закрытие определенного блока. Фигурная скобка в конце файла является закрывающей скобкой для следующего вложенного блока location:

…

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

…

Если просмотреть файл конфигурации еще дальше, то окажется, что в server block также отсутствует закрывающая фигурная скобка. Server block в Nginx важен, поскольку он предоставляет детали конфигурации, необходимые Nginx для определения того, какой виртуальный сервер будет обрабатывать получаемые запросы. Важно отметить, что location blocks вложены в server block, поскольку он имеет приоритет при обработке входящих запросов. Учитывая все это, для завершения server block в конце файла нужно добавить закрывающую фигурную скобку. Теперь содержимое этого файла будет выглядеть следующим образом:

server {
        listen 80;
        listen [::]:80;

        root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

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

После редактирования не забудьте сохранить и закрыть файл. Чтобы убедиться, что синтаксическая ошибка устранена, запустите sudo nginx -t.

Ошибка invalid host

Эта ошибка возникает из-за неверно сформированного параметра, заданного в директиве. Если завершение строк точкой с запятой и закрытие каждой фигурной скобки относится к общей структуре конфигурационного файла, то параметры – это пользовательские данные, которые могут варьироваться в зависимости от потребностей установки.

Отметим, что в этом сценарии действует директива host, но при недопустимых параметрах любая директива может быть подвержена этой ошибке. Соответственно, изменится и сообщение об ошибке:

[emerg] invalid host in "[::]80" of the "listen" directive in /etc/nginx/sites-enabled/your_domain:3
nginx: configuration file /etc/nginx/nginx.conf test failed

Сообщение объясняет, что установленная директива порта 80 недействительна. Сообщение об ошибке дополнительно указывает место обнаружения ошибки и точную строку в файле конфигурации: /etc/nginx/sites-enabled/your_domain:3. Обладая информацией о том, где найти ошибку, можно открыть файл в текстовом редакторе. Найдите строку 3, на которую ссылается сообщение:

server {
        listen 80;
        listen [::]80;

        root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

        server_name your_domain www.your_domain;

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

Два двоеточия в скобках представляют собой обозначение IPv6 или 0.0.0.0; без дополнительного двоеточия после скобки он не сможет привязаться к порту 80. В результате директива listen не будет работать, поскольку без двоеточия неясно, какой порт должен прослушивать сервер.

В общем, конкретная синтаксическая ошибка здесь заключается в том, что после скобки [::] не хватает двоеточия, а это делает параметр недействительным. После добавления пропущенного двоеточия, фрагмент кода в файле будет выглядеть следующим образом:

server {
        listen 80;
        listen [::]:80;
…

После обновления этой строки обязательно сохраните и закройте файл и убедитесь, что синтаксическая ошибка исправлена, выполнив команду sudo nginx -t.

В целом, при получении подобных синтаксических ошибок, связанных с параметрами, точками с запятой ; или фигурными скобками { }, рекомендуем обратить особое внимание на точное местоположение и детали в сообщении [emerg].

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

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

Ошибка unknown directive

Как упоминалось ранее, в основе файла конфигурации Nginx лежат директивы. У Nginx большой выбор директив, но есть несколько основных, необходимых практически в каждом в файле конфигурации. Однако существуют ошибки, которые могут возникнуть в самой директиве. Например, ключевое слово написано не совсем так, как должно быть. Вот пример такого сообщения об ошибке:

nginx: [emerg] unknown directive "serve_name" in /etc/nginx/sites-enabled/your_domain:8
nginx: configuration file /etc/nginx/nginx.conf test failed

Эта ошибка указывает на unknown directive “serve_name” в строке 8 файла конфигурации. Откройте файл с помощью текстового редактора:

server {
        listen 80;
        listen [::]:80;

        root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

        serve_name your_domain www.your_domain;

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

В данном примере ошибка — это неправильно написанное слово “server” в имени директивы server_name. В нем пропущена буква “r” и по этой причине директива не распознается. Это серьезная ошибка, поскольку в директиве server_name хранятся конкретные названия серверов, к которым будет обращаться server block при получении запроса. Без корректной работы этой директивы запрос не будет выполнен. Казалось бы, незначительная опечатка, но она нарушает синтаксис и вызывает ошибку. Обновите фрагмент кода в файле конфигурации следующим образом:

…

        server_name your_domain www.your_domain;

…

Сохраните и закройте файл. Проверьте его с помощью команды sudo nginx -t.

Ошибка directive is not allowed here

Теперь предположим, что возникла ошибка с той же директивой, но на этот раз сообщение выглядит так:

nginx: [emerg] "server" directive is not allowed here in /etc/nginx/sites-enabled/your_domain:8
nginx: configuration file /etc/nginx/nginx.conf test failed

Ошибка возникает в том же месте, что и предыдущая, причина проблемы подробно описана в этом сообщении. Поэтому важно понимать, на что указывает сообщение об ошибке. Эта ошибка указывает, что directive is not allowed here. Откройте файл конфигурации в текстовом редакторе:

server {
        listen 80;
        listen [::]:80;

        root /var/www/your_domain/html;
        index index.html index.htm index.nginx-debian.html;

        server name your_domain www.your_domain;

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

Здесь слово “server” написано правильно, но теперь тут отсутствует символ подчеркивания. Поэтому server воспринимается как дубликат, что недопустимо, о чем и говорит сообщение об ошибке. Это связано с различием между простыми и блочными директивами, о котором мы говорили ранее.

Эта ошибка связана с тем, что без подчеркивания server name читается просто как server и таким образом конфликтует с первой директивой server block в начале файла. Это сложная синтаксическая ошибка, которая может возникнуть из-за иерархической структуры Nginx в файле конфигурации среди блочных директив и вложенных простых директив. Исправить эту ошибку можно, добавив знак подчеркивания:

…

        server_name your_domain www.your_domain;

…

После внесения исправлений сохраните и закройте файл. Затем проверьте правильность синтаксиса с помощью команды sudo nginx -t. Если в файле конфигурации нет ошибок, должно появиться сообщение syntax is ok.

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

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

Здесь вы узнали о самых распространенных синтаксических ошибках, которые могут возникнуть с определенными директивами в файле конфигурации веб-сервера. Важно отметить, что все эти примеры представлены в среде терминала. Вы также можете использовать редактор кода, например Visual Studio Code, который может проверять и выделять ошибки в коде, не отправляя многочисленных уведомлений, что позволит исправить их все сразу или даже избежать их на ранней стадии.

Читайте также: Установка командной строки Visual Studio Code

Подводим итоги

В этом мануале мы разобрали распространенные синтаксические ошибки Nginx и поговорили о том, как их исправить. Несмотря на то, что вы можете столкнуться с разными синтаксическими ошибками Nginx, эти примеры дают представление о решениях наиболее частых из них. 

Читайте также: Структура и контексты конфигурационного файла Nginx