Nginx配置常见语法错误及高效排查指南
Nginx语法常见错误：配置与排查（第一部分）
Nginx作为一款流行的Web服务器，广泛应用于托管大型和高流量网站。在配置Nginx时，通常会通过创建包含配置细节的“域块”来确保网站能正确处理传入请求。然而，Nginx配置过程中常见的错误之一就是配置文件中的语法问题。本系列文章将深入探讨Nginx语法错误及其解决方案。
本指南中的示例已在Ubuntu 22.04服务器上进行测试，但由于主要涉及标准化的配置文件，因此适用于大多数Nginx安装。请注意，具体的目录和路径可能略有不同。
在本教程中，您将学习Nginx配置文件中可能出现的语法错误，以及如何检查和纠正这些错误。
检查您的Nginx错误日志
本教程中提供的错误和解决方案是常见情况，但并非详尽无遗。由于语法错误可能会破坏Nginx所认为的有效语句结构，以下错误仅作为Nginx响应的指导。通常情况下，一个错误可能会引发另一个错误，并且错误可能是更大或独立问题的症状。您的具体情况和设置可能会有所不同。
请注意，您可以随时查阅Nginx错误日志以查看正在运行的列表：
- sudo cat /var/log/nginx/error.log
本教程将在后续内容中分解和理解Nginx错误信息的部分。
测试您的配置文件是否有错误
为了本教程的目的，我们将引用一个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的配置文件主要围绕指令展开，并且这些指令必须以特定的方式进行声明。否则，您的配置文件将不具备结构上的有效性。
指令可以分为两种不同类型，每种类型都有特定的语法。可以有简单指令，包含指令名称和参数，以分号结束。也可以有块指令，类似于单个指令，但用花括号 { } 标记，甚至可以包含其他块在其中。
当指令构造不当时，Nginx将无法将其识别为您所期望的指令，并可能导致以下错误。
Nginx参数无效错误
Nginx的配置文件在正确的结构和语法方面非常讲究。事实上，您的语法可能出现的一个问题与分号 ; 相关。例如，考虑以下错误信息：
[emerg] invalid parameter "root" in /etc/nginx/sites-enabled/example.com:5
nginx: configuration file /etc/nginx/nginx.conf test failed
在解决这个问题之前，您应该了解Nginx错误信息的组成。错误信息中有一些提示，可以帮助您确定错误的原因。在这个例子中，[emerg] 代表“紧急”，表示与系统不稳定有关的错误信息。在这种情况下，这意味着Nginx遇到了一个阻止它正常工作的问题。
这个错误消息进一步指明了错误的位置。请记住，在Nginx的设置中，您将拥有一个自定义配置文件，它通过符号链接连接到/etc/nginx/nginx.conf。例如，如果您按照我们在Ubuntu 22.04上安装Nginx的指南操作，第5步特别演示了这一点。错误的确切配置文件行是：/etc/nginx/sites-enabled/example.com:5。您还了解到该文件中有一个无效的参数“root”。
现在您已经知道错误的位置，可以继续使用您喜欢的文本编辑器打开文件。在这里，我们将使用nano。
注意：如果您有任何疑问，通常可以在 /etc/nginx/ 目录中找到所有的配置文件。请在我们的教程中阅读更多关于其他重要的Nginx文件和目录的信息。
- sudo nano /etc/nginx/sites-available/example.com
进入后，请找到错误信息所提到的第5行。该行在以下所示的内容中被突出显示。
文件路径：/etc/nginx/sites-available/example.com
server {
listen 80;
listen [::]:80;
root /var/www/example.com/html
index index.html index.htm index.nginx-debian.html;
server_name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
}
现在，这里发生的错误可能不明显。如果您回想起错误信息，那里有一个无效的参数。作为提醒，参数是您提供给Nginx指令的参数。虽然在这种情况下提供的参数是/var/www/example.com/html，但它是无效的。在语法结构中有一个缺失的字符，即在该行末尾缺少一个分号。
您可能会注意到，这个文件中的许多其他行也以分号结束。只要一行包含指示符，分号是必需的。这个特定的例子是指定在搜索文件时将使用的根目录的根指示。有了这个根指示，Nginx才能找到特定的URL路径。我们将在后面的章节中讨论指示的重要性。
简而言之，为了确保指令有效，您可以通过在该行末尾添加一个分号来修复此错误。您的更新将如下：
文件路径：/etc/nginx/sites-available/example.com
…
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
…
更新完成后，请保存并关闭文件。如果您使用的是nano编辑器，可以按CTRL + X，然后按Y和回车来完成。
通过运行sudo nginx -t命令，您可以验证您的语法错误是否被修复。
Nginx 出现意外的“}”错误
在Nginx的语法结构中，另一个常见的错误是花括号{}的使用。与之前错误不同的是，这个错误明确提供了错误的原因，但没有指定如何纠正无效参数。
nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/example.com:15
nginx: configuration file /etc/nginx/nginx.conf test failed
这个错误信息是另一种[emerg]类型的，它在第15行指出在之前的同一配置文件中有一个意外的大括号。使用您偏好的文本编辑器打开该文件，其内容将如下：
文件路径：/etc/nginx/sites-available/example.com
server {
listen 80;
listen [::]:80;
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
server_name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
在该文件末尾的地方用大括号“}”做了标记。乍一看，问题可能不太明显，因为这个意外的“}”似乎是存在的。仔细检查后，实际上缺少了一个大括号。在Nginx配置文件中，正确的大括号数量很重要，因为它表示特定块的开启和关闭。如果您仔细观察，您会发现文件末尾的大括号实际上是下一个嵌套位置块的闭合大括号。
文件路径：/etc/nginx/sites-available/example.com
这是文章《Nginx语法常见错误》的第2部分（共3部分）。
…
location / {
try_files $uri $uri/ =404;
}
…
如果你进一步审查配置文件的内容，你会发现缺少了一个闭合的右花括号。一个Nginx服务器块非常重要，因为它提供了Nginx识别哪个虚拟服务器来处理各种接收到的请求的配置信息。需要注意的是，位置块是嵌套在服务器块中的，因为服务器块在处理传入请求时有优先权。在这种情况下，你可以在文件末尾添加闭合的右花括号，以完成服务器块。该文件的内容现在将如下所示：
server {
listen 80;
listen [::]:80;
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
server_name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
}
当完成操作后，请记得保存并关闭文件。通过运行sudo nginx -t确认该语法错误是否已被解决。
Nginx的无效主机错误
这个错误与前两个不同，因为错误是由给指令的参数造成的。虽然在配置文件中，以分号;结尾的行和用}闭合的每个大括号{有助于处理整体结构，但参数是可以根据您的设置需求进行定制的输入。
应该注意到，在这种情况下，受影响的指令是host，但任何指令都可能受到这种错误的影响，只要提供了无效的参数。错误消息会相应地改变。提供有效的参数可以确保避免像以下情况这样的错误。
[emerg] invalid host in "[::]80" of the "listen" directive in /etc/nginx/sites-enabled/example.com:3
nginx: configuration file /etc/nginx/nginx.conf test failed
在这个例子中，紧急错误解释说为您主机设置的端口80指令无效。此错误消息进一步确定了可以找到该错误的位置，并且给出了配置文件中的确切行号：/etc/nginx/sites-enabled/example.com:3。现在您知道了错误的位置，可以使用您喜爱的文本编辑器打开该文件。进入文件后，找到错误消息所指的第3行。以下是被突出显示的行：
server {
listen 80;
listen [::]80;
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
server_name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
}
括号中的两个冒号::代表IPv6表示法，或者是0.0.0.0。如果括号后没有附加冒号，它将无法绑定到80端口。因此，没有冒号的话，服务器无法明确监听哪个端口，导致listen指令无法工作。
简而言之，在此处发生的具体语法错误是方括号[::]后缺少了冒号，使得参数本身无效。一旦添加缺少的冒号，你文件中的代码片段将如下所示：
server {
listen 80;
listen [::]:80;
…
在更新这一行之后，请确保保存并关闭文件，然后通过运行sudo nginx -t来验证是否已经修正了这个语法错误。
总体来说，当遇到与参数、分号;或花括号{}有关的语法错误时，建议您密切关注[emerg]消息中提供的确切位置和详细信息的细节。
在Nginx配置文件中识别指令错误
除了由于缺少冒号或花括号可能导致的语法错误之外，您的配置文件中与指令相关的关键词的拼写错误也可能出现错误。我们在前面的部分简要提到了指令，现在让我们再次回顾一下。
Nginx的未知指令错误
如前所述，Nginx配置文件的基础是指令。Nginx有许多可供选择的指令，但在配置文件中需要一些主要的指令。然而，指令本身可能存在错误，尤其是如果关键字的书写不完全正确。以下是您可能收到的错误消息的示例：
nginx: [emerg] unknown directive "serve_name" in /etc/nginx/sites-enabled/example.com:8
nginx: configuration file /etc/nginx/nginx.conf test failed
这个错误在第8行中的配置文件中标识出一个未知指令serve_name。当你使用你喜欢的文本编辑器打开配置文件时，你的内容将列出如下：
server {
listen 80;
listen [::]:80;
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
serve_name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
}
在这个例子中，触发的错误是由于server_name指令中“server”单词的拼写错误导致的。在这种情况下，缺少一个“r”，因此无法识别这个单一指令。这是一个重大错误，因为server_name指令提供了在收到请求时，服务器块将参考的具体服务器名称。如果没有这个指令正确运行，请求无法完成。这可能是一个看似小的拼写错误，但它破坏了语法，导致错误。您可以在配置文件中将此代码片段更新为以下内容：
…
server_name example.com www.example.com;
…
在保存并关闭此文件后，您可以使用sudo nginx -t命令验证其是否正常工作。
Nginx的指令在此处不被允许的错误
现在，假设您在相同的指令中出现错误，但这次的消息如下所示：
nginx: [emerg] "server" directive is not allowed here in /etc/nginx/sites-enabled/example.com:8
nginx: configuration file /etc/nginx/nginx.conf test failed
您可能会注意到，尽管此错误发生在与先前的错误相同的位置，但问题的原因在此消息中有详细说明。因此，重要的是要理解错误消息所指示的内容。与之前关于“未知指令”的错误消息不同，此错误指出“server”指令不允许使用。您可以使用您首选的文本编辑器打开配置文件来检查其内容。
server {
listen 80;
listen [::]:80;
root /var/www/example.com/html;
index index.html index.htm index.nginx-debian.html;
server name example.com www.example.com;
location / {
try_files $uri $uri/ =404;
}
}
这里的单词“server”拼写正确，但是指令本身没有使用正确的server_name指令的下划线作为标记。因此，server被视为一个重复项，而错误消息中明确说明不允许重复。这与我们之前讨论过的单个指令和块指令之间的区别有关。
这里触发的错误是因为单个指令server name只读取了server，从而与文件开始的第一个服务器块指令发生冲突。这是一个棘手的语法错误，可能会在块指令和嵌套单个指令之间发生，因为Nginx在配置文件中有一个层次结构。您可以通过在server_name指令的确切关键字前添加下划线_来纠正这个错误。
…
server_name example.com www.example.com;
…
一旦你做出这个修正，保存并关闭文件。接着用sudo nginx -t检查语法是否有效。除非你的配置文件中还有其他错误，否则应该会返回句法正确的信息。
注意
注意：在Nginx配置文件中，空格或换行的数量具有一定的灵活性，不会引发任何错误。然而，任何明确与指令相关的内容都会返回错误，因为必须使用准确的措辞或语法结构才能正常运行。最后提醒的是，如果您的配置文件中包含多个错误，您会一次只收到一个错误信息，按顺序连续返回。这意味着，如果您收到有关某个问题的错误消息，纠正之后再次运行语法检查命令，下一个错误将在输出中返回。这种情况将持续发生，直到所有错误被纠正为止。
现在您已经了解了在配置文件中可能出现的特定指令的其他语法错误。需要注意的是，所有这些例子都以终端环境表示。如果您愿意，可以选择使用代码编辑器，比如Visual Studio Code，它可以检查并突出显示代码中的错误，而不会触发多个错误消息，这样可以一次性进行修正，或者尽早避免这些错误。
结论
在本教程中，您了解了Nginx的常见语法错误以及如何纠正它们。尽管您可能会遇到许多Nginx语法错误，但这些示例提供了一些最常见错误的可能性和解决方案。如果您对了解Nginx配置文件感兴趣，可以参考我们的相关教程。您还可以查看我们标记的社区页面上的其他Nginx内容，或者开始学习如何在Ubuntu 22.04上安装Nginx。
