格式及语法

nginx 由模块组成，这些模块由配置文件中指定的指令控制。指令分为简单指令和块指令。

• 简单指令：由名称和参数组成，由空格分隔并以分号 (😉 结尾。

• 指令块：与简单指令具有相同的结构，但它不是以分号结尾，而是以一组用大括号（{ 和 }）包围的附加指令结束。

• 上下文：如果块指令可以在大括号内包含其他指令，则称为上下文（例如：event、http、server和location）。放置在任何上下文之外的配置文件中的指令被认为是在 main 上下文中。event 和 http 指令在 main 上下文中，server 在 http 里面，location 在 server 里面。

  event {
  
  }
  
  http {
    server {
      location {
      
      }
    }
  }

• 注释： # 后面的即为注释

常用配置

通用上下文

include

include file | mask;

将另一个文件或与指定掩码匹配的文件包含到配置中。include 的这个文件应该由正确语法的指令和指令块组成。

例如：

include mime.types;
include vhosts/*.conf;

main 上下文

user

定义工作进程使用的用户和组凭据。如果省略 group，则使用名称与 user 相同的组。

Syntax:	user user [group];
Default:	user nobody nobody;

worker_processes

定义工作进程的数量。最佳值取决于许多因素，包括（但不限于）CPU 内核数量、存储数据的硬盘驱动器数量和负载模式。（值“auto”将尝试自动检测它）。

| Syntax: | worker_processes number | auto | | :------- | -------------------------------------- | | Default: | worker_processes 1; |

error_log

配置日志记录。可以在同一配置级别上指定多个日志。如果在主配置级别上未明确定义将日志写入文件，则将使用默认文件。

可用于 main，http，mail，stream，server，location 上下文。

• 第一个参数定义将存储日志的文件。特殊值 stderr 选择标准错误文件。可以通过指定“syslog:”前缀来配置日志记录到 syslog。可以通过指定“memory:”前缀和缓冲区大小来配置记录到循环内存缓冲区。
• 第二个参数确定日志记录的级别，可以是以下之一：debug、info、notice、warn、error、crit、alert 或 emerg。默认为 error。如果设置了一个级别，那么将会输出大于这个级别的日志，比如设置 alert，则输出 alert 和 emerg 级别的日志。

Syntax:	error_log file [level];
Default:	error_log logs/error.log error;

daemon

确定 nginx 是否应该成为守护进程。主要在开发过程中使用。

# 默认是 off
daemon off | on;

event 上下文

accept_mutex

当一个新连接到达时，如果激活了accept_mutex，那么多个Worker将以串行方式来处理，其中有一个Worker会被唤醒，其他的Worker继续保持休眠状态；如果没有激活accept_mutex，那么所有的Worker都会被唤醒，不过只有一个Worker能获取新连接，其它的Worker会重新进入休眠状态，这就是「惊群问题 (opens new window)」。

Nginx默认激活了accept_mutex（最新版默认禁用），是一种保守的选择。如果关闭了它，可能会引起一定程度的惊群问题，表现为上下文切换增多（sar -w）或者负载上升，但是如果你的网站访问量比较大，为了系统的吞吐量，我还是建议大家关闭它。

Syntax:	accept_mutex on | off;
Default:	accept_mutex off;

multi_accept

如果 multi_accept 被禁用，工作进程将一次接受一个新连接。否则，工作进程将一次接受所有新连接。

如果使用 kqueue 连接处理方法，则忽略该指令，因为它报告等待接受的新连接数。

Syntax:	multi_accept on | off;
Default:	multi_accept off;

use

指定要使用的连接处理方法。通常不需要显式指定它，因为默认情况下 nginx 将使用最有效的方法。

Syntax:	use method;
Default:	—

event {
  use kqueue;
}

其他 method 可见 events (opens new window)

worker_aio_requests

aio 配合 epoll 连接处理方式使用时(use epoll)，设置单个 worker 进程的最大未完成异步I/O操作数。

Syntax:	worker_aio_requests number;
Default:	worker_aio_requests 32;

worker_connections

设置工作进程可以同时打开的最大连接数。 应该记住，这个数字包括所有连接（例如与代理服务器的连接等），而不仅仅是与客户端的连接。另一个考虑是实际同时连接数不能超过当前最大打开文件数限制，可以通过worker_rlimit_nofile来改变。

Syntax:	worker_connections number;
Default:	worker_connections 512;

http 上下文

default_type

定义响应的默认 MIME 类型。可以使用 types 指令设置文件扩展名到 MIME 类型的映射。

Syntax:	default_type mime-type;
Default:	default_type text/plain;

server

设置虚拟服务器的配置。基于 IP 地址和基于 Host 的虚拟服务器之间没有明确的区别。相反，listen 指令描述了应该接受服务器连接的所有地址和端口，并且 server_name 指令列出了所有服务器名称。

server {
    server_name example.com www.example.com;
}

listen

设置 IP 的地址和端口，或服务器将接受请求的 UNIX 域套接字的路径。可以同时指定地址和端口，或者只指定地址或只指定端口。地址也可以是主机名。

语法格式

listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]; 示例

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

listen [::]:8000;
listen [::1];

listen unix:/var/run/nginx.sock;

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location

根据请求 URI 设置配置。 在解码以“%XX”形式编码的文本、解析对相对路径组件“.”的引用后，对规范化的 URI 执行匹配。和“..”，以及可能将两个或多个相邻的斜线压缩成一个斜线。

Syntax:	location [ = | ~ | ~* | ^~ ] uri { ... } location @name* { ... }
Default:	—

例子

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

• “/”请求将匹配配置 A
• “/index.html”请求将匹配配置 B
• “/documents/document.html”请求将匹配配置 C
• “/images/1.gif”请求将匹配配置 D
• “/documents/1.jpg”请求将匹配配置 E。

root

设置请求的根目录。

Syntax:	root path;
Default:	root html;

例子

location /i/ {
    root /data/w3;
}

/data/w3/i/top.gif 文件将被发送以响应/i/top.gif请求。

路径值可以包含变量，但 $document_root 和$realpath_root. 除外。

sendfile

启用或禁用 sendfile() 的使用。

Syntax:	sendfile on | off;
Default:	sendfile off;