Nginx配置文件语法和核心功能配置项详解

nginx的配置文件只是一个普通的文本文件。

简单的例子

user nobody;
worker_processes 8;
error_log varlog/nginx/error.log error;
#pid logs/nginx.pid;
events {
use epoll;
worker_connections 50000;
} h
ttp {
include mime.types;
default_type application/octet-stream;
log_format main '$remote_addr [$time_local] "$request" '
'$status $bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log logs/access.log main buffer=32k;
…

配置项与值用空格分开，多个值用空格分开。结尾用分号结束。
如果配置项值中包括语法符号（关键字）， 比如空格符， 那么需要使用单引号或双引号
括住配置项值， 否则Nginx会报语法错误。

块配置项：

块配置项是由一个块配置项名和一对大括号组成。

events{
	.....
}

http{
	gzip on;
	......
	server {
		......
		location /webstatic {
			gzip off;
		}
	}
}

块配置项可以嵌套。 内层块直接继承外层块 例如， 上例中， server块里的任意配置都是基于http块里的已有配置的。 当内外层块中的配置发生冲突时， 究竟是以内层块还是外层块的配置为准， 取决于解析这个配置项的模块. 例如， 上例在http模块中已经打开了“gzip on;”， 但其下的location/webstatic又把gzip关闭了： gzip off;， 最终， 在/webstatic的处理模块中， gzip模块是按照gzip off来处理请求的。

//在外面的属于main上下文的配置
user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
	//里面属于events上下文的配置
    use kqueue;
    worker_connections 2048;

http{
	include mines.types;
	default_type application/octet-stream;
	server{
	}
}
}

配置项的单位

大部分模块遵循一些通用的规定， 如指定空间大小时默认字节、 指定时间时默认毫秒。

空间大小单位：
5k ： 5kb。
5M：5mb。

时间大小单位：
5ms：5毫秒。
5s：5秒。
5m：5分钟。
5h：5小时。
5d：5天。
5w：5周/40天。
5M：5个月/150天。
5y：5年/365*5天。

accept_mutex

配置语法：accept_mutex on|off
默认：accept_mutex off
上下文：events

这个配置的作用是:
如果accept_mutex 配置为on，也就是开启（enable）状态时，当一个新连接到达，那么多个Worker将以串行方式来处理（通过一个进程互斥锁），其中有一个Worker会被唤醒，其他的Worker继续保持休眠状态；其他Worker进程接收新连接要等这个锁释放。

如果accept_mutex 配置为off，也就是关闭（disEnable）状态时，当一个新连接到达，那么多个Worker将全部被唤醒去竞争资源，不过只有一个Worker能获取新连接，其它的Worker会重新进入休眠状态。

也就是说开启了的话，每次来新请求，就只会唤醒一个Worker进程。如果关闭off的话，每次来新请求就把所有Worker进程唤醒。

因为nginx不像apache那样有成百上千个进程，nginx一般会启动跟服务器CPU核心数一样的Worker进程，所以就算每次唤醒所有Worker来竞争影响都还好，不会造成大量上下文切换。

这是一种典型的惊群问题。

比如有一群小鸡，每次撒一粒米，然后全部来争抢这粒米，但是只有一只鸡能成功，其他抢不到的就铩羽而归，这是惊群。也就是off的情况，小鸡比喻worker进程，米比喻连接。而on的情况是，每次不惊动其他小鸡抓其中一只过来，喂了那粒米，再把他放回去。

但是如果有一盘米（大量），如果使用on的情况的话，一粒抓一只小鸡来喂的话，效率会很低，如果使用off情况，一下子把米撒向小鸡，然后全部小鸡就抢夺米粒。这样效率会高上许多。

所以如果在处理大并发连接时，使用on模式的话，每个连接都会串行唤醒Worker来处理，这效率无疑是太低了，如果使用off，Worker进程全部唤醒来争抢所有连接的话，效率就会高很多。但是这样会导致worker进程之间的负载不均衡。

lock_file

语法：lock_file file
默认：lock_file logs/nginx.lock
上下文：events

accept锁可能需要这个lock文件， 如果accept锁关闭（accept_mutex off）， lock_file配置完全不生效。 如果打开了accept锁， 并且由于编译程序、 操作系统架构等因素导致Nginx不支持原子锁， 这时才会用文件锁实现accept锁 ， 这样lock_file指定的lock文件才会生效。

accept_mutex_delay

语法： accept_mutex_delay time;
默认: accept_mutex_delay 500ms;
上下文: events

这个配置只有当accept_mutex配置为on时才生效，在使用accept锁后， 同一时间只有一个worker进程能够取到accept锁。 这个accept锁不是阻塞锁， 如果取不到会立刻返回。 如果有一个worker进程试图取accept锁而没有取到， 它至少要等accept_mutex_delay定义的时间间隔后才能再次试图取锁。

在使用accept锁后， 同一时间只有一个worker进程能够取到accept锁。 这个accept锁不是
阻塞锁， 如果取不到会立刻返回。 如果有一个worker进程试图取accept锁而没有取到， 它至
少要等accept_mutex_delay定义的时间间隔后才能再次试图取锁。

可以把时间调小一点，减少间隔。提升性能。

daemon

语法: daemon on | off;
默认: daemon on;
上下文: main
是否把nginx以守护进程的方式启动。

error_log

语法: error_log file [level];
默认: error_log logs/error.log error;
上下文: main, http, mail, stream, server, location

配置错误日志文件的路径和日志级别。日志级别是可选的。默认error。
日志级别的取值范围有：debug、 info、 notice、 warn、 error、 crit、 alert、
emerg， 从左至右级别依次增大。 当设定为一个级别时， 大于或等于该级别的日志都会被输
出到pathfile文件中， 小于该级别的日志则不会输出。比如设置为error，则会输出error、crit、alert、emerg级别日志，不会输出debug、info、botice、warn日志。
关闭错误日志的唯一方式：error_log /dev/null .

debug_connection

语法：debug_connection [IP|CIDR]
默认：------
上下文：events

对指定客户端输出debug日志。他的值可以是IP或者CIDR地址。
比如：

events {
debug_connection 10.224.66.14;
debug_connection 10.224.57.0/24;
}

这样，仅仅来自上述ip的请求才会输出debug日志，其他请求仍然沿用error_log配置的日志级别。
这个配置对修复bug很有用，特别是定位高并发请求下才会发生的问题。

使用debug_connection前， 需确保在执行configure时已经加入了–with-debug参数， 否则不会生效。

include

语法: include file | mask;
默认: —
上下文: any 任意

在配置文件中包含（嵌入）另一个或多个配置文件。包含的文件应该由语法正确的指令和块组成。可以实现多文件配置，然后用一个文件汇总。

比如：
include mime.types; //表示纳入mime.types文件的配置，mime.types是代表多媒体类型的文件，比如application/xml等。

include vhosts/*.conf; //表示包含vhosts目录下所有已.conf结尾的文件。

multi_accept

语法: multi_accept on | off;
默认: multi_accept off;
上下文: events

如果开启，表示worker进程可以同时接收多个新连接，如果关闭，表示worker同一时间只能接收一个新连接。当事件模型通知有新连接时， 尽可能地对本次调度中客户端发起的所有TCP请求都建立
连接

pcre_jit

语法: pcre_jit on | off;
默认: pcre_jit off;
上下文: main
nginx 1.1.12 后出现

开启或者关闭对配置解析时已知的正则表达式使用“实时编译”，默认关闭，如果开启可以显著加快正则表达式的处理速度。如果要使用，则安装nginx时需要带上pcre库。

pid

语法: pid file;
默认: pid logs/nginx.pid;
上下文: main

指定master进程的进程号记录文件。

user

语法: user user [group];
默认: user nobody nobody;
上下文: main

指定工作进程使用的用户或者用户组权限，这关系到该进程对系统文件等等的操作权限。group是可选的，如果不配置，则默认使用user的值，比如 user yhc ；则用户组为yhc。

worker_connections

语法: worker_connections number;
默认: worker_connections 512;
上下文: events

设置每个工作进程能同时打开的最大连接数，这个连接数不仅仅代表与客户端的连接，而是所有连接，比如包括与代理服务器的连接等。同时连接的实际数量不能超过当前对打开文件的最大数量的限制，该限制可以由worker_rlimit_nofile更改。

也就是 worker_connections <=worker_rlimit_nofile<=内核参数fs.file-max

worker_priority

语法: worker_priority number;
默认: worker_priority 0;
上下文: main

定义工作进程的调度优先级，就像使用nice命令一样：负数表示优先级更高。允许的范围通常在-20到20之间。

worker_processes

语法: worker_processes number | auto;
默认: worker_processes 1;
上下文: main

每个worker进程都是单线程的进程， 它们会调用各个模块以实现多种多样的功能。 如果这些模块确认不会出现阻塞式的调用， 那么， 有多少CPU内核就应该配置多少个进程； 反之， 如果有可能出现阻塞式调用， 那么需要配置稍多一些的worker进程。

多worker进程可以充分利用多核系统架构， 但若worker进程的数量多于CPU内核数， 那么会增大进程间切换带来的消耗（Linux是抢占式内核） 。 一般情况下， 用户要配置与CPU内核数相等的worker进程， 并且使用worker_cpu_affinity配置来绑定CPU内核。

worker_cpu_affinity

语法: worker_cpu_affinity cpumask …;
默认: —
上下文: main

将工作进程绑定到CPU集。每个CPU集由允许的CPU的位掩码表示。应该为每个工作进程定义一个单独的集合。默认情况下，工作进程不绑定到任何特定的cpu。如果每个工作进程绑定到一个CPU的话，Worker进程之间就不会存在进程的上下文切换，但是还是会跟其他进程切换。

为什么要绑定worker进程到指定的CPU内核呢？ 假定每一个worker进程都是非常繁忙的， 如果多个worker进程都在抢同一个CPU， 那么这就会出现同步问题，并且存在上下文切换开销。 反之， 如果每一个worker进程都独享一个CPU， 就在内核的调度策略上实现了完全的并发。

该配置只对linux系统有效。

比如：
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

worker_shutdown_timeout

语法: worker_shutdown_timeout time;
默认: —
上下文: main
nginx 1.11.11之后出现.

设置nginx进程正常关闭的超时时间，如果超时时间内没有关闭掉nginx进程，nginx会尝试关闭所有当前打开的连接，以便于关闭。默认超时，知道正常关闭为止。

worker_rlimit_nofile

语法：worker_rlimit_nofile number
默认：----
上下文：main

表示每个工作进程能够同时打开的文件句柄数，因为在linux系统中，所有都是以文件的形式表示，所以能够打开的文件句柄数直接也代表了nginx能够同时接收的最大客户端连接数。事实上往往要比这个小一些，除了客户端连接以外还会有其他连接。

use

语法： use method
默认：----
上下文：events

选择事件模型。有 epoll、poll、select、kqueue。这个一般不用设置，会自动使用最佳的，epoll是效率比poll和select高很多的多路复用。epoll是linux2.6以上内核以上才支持的功能，epoll事件模式是nginx高并发的核心，所以如果要实现nginx高并发web服务器，就保证使用的linux内核在2.6以上。