核心功能

user www www;
worker_processes 2;

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

events {
    use kqueue;
    worker_connections 2048;
}

...

accept_mutex off;

如果启用 accept_mutex，工作进程将轮流接受新连接。否则，所有工作进程都将收到新连接的通知，如果新连接的数量较少，一些工作进程可能会浪费系统资源。

在支持 EPOLLEXCLUSIVE 标志（1.11.3）的系统上或使用 reuseport 时，无需启用 accept_mutex。

在 1.11.3 版本之前，默认值为 on。

accept_mutex_delay 500ms;

如果启用了 accept_mutex，则指定如果另一个工作进程当前正在接受新连接，工作进程尝试重新开始接受新连接的最长等待时间。

daemon on;

决定 nginx 是否应作为守护进程运行。主要在开发过程中使用。

为选定的客户端连接启用调试日志。其他连接将使用 error_log 指令设置的日志级别。被调试的连接通过 IPv4 或 IPv6（1.3.0, 1.2.1）地址或网段指定。也可以使用主机名指定连接。对于使用 UNIX 域套接字（1.3.0, 1.2.1）的连接，通过“unix:”参数启用调试日志。

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

要使此指令生效，nginx 需要在构建时包含 --with-debug，请参阅“调试日志”。

此指令用于调试。

当检测到内部错误时，例如工作进程重启时套接字泄漏，启用 debug_points 会导致生成核心转储文件（abort）或停止进程（stop），以便使用系统调试器进行进一步分析。

env TZ;

默认情况下，nginx 会移除从父进程继承的所有环境变量（TZ 变量除外）。此指令允许保留部分继承的变量、修改它们的值或创建新的环境变量。这些变量随后会：

• 在可执行文件的 热升级 期间继承；
• 被 ngx_http_perl_module 模块使用；
• 被工作进程使用。需要注意的是，通过这种方式控制系统库并不总是可行的，因为库通常只在初始化期间检查变量，而这往往早于使用此指令设置变量的时间。上述 热升级 可执行文件的情况是例外。

除非显式配置，否则 TZ 变量总是会被继承并可供 ngx_http_perl_module 模块使用。

用法示例

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

NGINX 环境变量由 nginx 内部使用，不应由用户直接设置。

error_log logs/error.log error;

配置日志记录。可以在同一个配置级别指定多个日志（1.5.2）。如果在 main 配置级别没有明确定义将日志写入文件，则使用默认文件。

第一个参数定义用于存储日志的 file。特殊值 stderr 选择标准错误文件。可以通过指定“syslog:”前缀来配置记录到 syslog。可以通过指定“memory:”前缀和缓冲区 size 来配置记录到 循环内存缓冲区，这通常用于调试（1.7.11）。

第二个参数确定日志的 level，可以是以下值之一：debug、info、notice、warn、error、crit、alert 或 emerg。上述日志级别按严重性递增排列。设置特定的日志级别将导致记录指定级别及更严重级别的所有消息。例如，默认级别 error 将记录 error、crit、alert 和 emerg 消息。如果省略此参数，则使用 error。

要使 debug 日志生效，nginx 需要在构建时包含 --with-debug，请参阅“调试日志”。

该指令从 1.7.11 版本开始可在 stream 级别使用，从 1.9.0 版本开始可在 mail 级别使用。

提供配置文件的上下文，在此上下文中指定影响连接处理的指令。

将另一个 file 或匹配指定 mask 的文件包含到配置中。被包含的文件应包含语法正确的指令和块。

用法示例

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

加载动态模块。

示例

load_module modules/ngx_mail_module.so;

lock_file logs/nginx.lock;

nginx 使用锁定机制来实现 accept_mutex 并序列化对共享内存的访问。在大多数系统上，锁是使用原子操作实现的，该指令会被忽略。在其他系统上，使用“锁文件”机制。此指令指定锁文件名称的前缀。

master_process on;

决定是否启动工作进程。此指令旨在供 nginx 开发人员使用。

multi_accept off;

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

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

pcre_jit off;

启用或禁用对配置解析时已知的正则表达式使用“即时编译”（PCRE JIT）。

PCRE JIT 可以显著加快正则表达式的处理速度。

JIT 在 8.20 版本及以上且使用 --enable-jit 配置参数构建的 PCRE 库中可用。当 PCRE 库与 nginx 一起构建（--with-pcre=）时，JIT 支持通过 --with-pcre-jit 配置参数启用。

pid logs/nginx.pid;

定义用于存储主进程进程 ID 的 file。

定义硬件 SSL 加速器的名称。

该模块可能在配置测试期间由 OpenSSL 动态加载。

ssl_object_cache_inheritable on;

如果启用，SSL 对象（SSL 证书、私钥、受信任的 CA 证书、CRL 列表）将在配置重载时被继承。

如果自上次配置加载以来，从文件加载的 SSL 对象的修改时间和文件索引未发生变化，则它们会被继承。指定为 engine:name:id 的私钥永远不会被继承。指定为 data:value 的私钥总是被继承。

从变量加载的 SSL 对象无法被继承。

示例

ssl_object_cache_inheritable on;

http {
    ...
    server {
        ...
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

stall_threshold 1000ms;

允许覆盖在报告停滞（stall）之前的默认事件循环迭代时间阈值。默认情况下，当事件循环迭代超过 1000ms 时会报告停滞。如果启用了 timer_resolution 指令，则该时间阈值将被忽略。

该指令是我们的商业订阅的一部分。

thread_pool default threads=32 max_queue=65536;

定义线程池的 name 和参数，用于不阻塞工作进程的多线程文件读取和发送。

threads 参数定义池中的线程数。

如果池中的所有线程都忙，新任务将在队列中等待。max_queue 参数限制允许在队列中等待的任务数量。默认情况下，队列中最多可等待 65536 个任务。当队列溢出时，任务将以错误结束。

降低工作进程中的计时器分辨率，从而减少 gettimeofday() 系统调用的次数。默认情况下，每次接收到内核事件时都会调用 gettimeofday()。降低分辨率后，每指定的 interval 只调用一次 gettimeofday()。

示例

timer_resolution 100ms;

该间隔的内部实现取决于所使用的方法：

• 如果使用 kqueue，则为 EVFILT_TIMER 过滤器；
• 如果使用 eventport，则为 timer_create()；
• 否则为 setitimer()。

指定要使用的 连接处理 method。通常无需显式指定，因为 nginx 默认会使用最高效的方法。

user nobody nobody;

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

worker_aio_requests 32;

在使用带有 epoll 连接处理方法的 aio 时，设置单个工作进程的未完成异步 I/O 操作的最大 number。

worker_connections 512;

设置单个工作进程可以打开的最大并发连接数。

需要记住的是，此数字包括所有连接（例如与代理服务器的连接等），而不仅是与客户端的连接。此外，实际的并发连接数不能超过当前打开文件的最大数量限制，该限制可以通过 worker_rlimit_nofile 进行修改。

将工作进程绑定到 CPU 集合。每个 CPU 集合由允许的 CPU 的位掩码表示。每个工作进程应定义一个单独的集合。默认情况下，工作进程不会绑定到任何特定的 CPU。

例如：

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

将每个工作进程绑定到单独的 CPU，而

worker_processes    2;
worker_cpu_affinity 0101 1010;

将第一个工作进程绑定到 CPU0/CPU2，第二个工作进程绑定到 CPU1/CPU3。第二个示例适用于超线程。

特殊值 auto（1.9.10）允许将工作进程自动绑定到可用 CPU。

worker_processes auto;
worker_cpu_affinity auto;

可选的 mask 参数可用于限制自动绑定的可用 CPU。

worker_cpu_affinity auto 01010101;

该指令仅在 FreeBSD 和 Linux 上可用。

worker_priority 0;

定义工作进程的调度优先级，类似于 nice 命令：负的 number 表示优先级更高。允许的范围通常在 -20 到 20 之间。

示例

worker_priority -10;

worker_processes 1;

定义工作进程的数量。

最佳值取决于许多因素，包括（但不限于）CPU 核心数、存储数据的硬盘驱动器数量以及负载模式。如有疑问，将其设置为可用 CPU 核心数是一个很好的起点（值“auto”将尝试自动检测）。

auto 参数从 1.3.8 和 1.2.5 版本开始支持。

更改工作进程核心转储文件的最大大小限制（RLIMIT_CORE）。用于在不重启主进程的情况下增加限制。

更改工作进程的最大打开文件数限制（RLIMIT_NOFILE）。用于在不重启主进程的情况下增加限制。

配置工作进程优雅关闭的超时时间。当 time 届满时，nginx 将尝试关闭当前所有打开的连接以辅助关闭。

定义工作进程的当前工作目录。它主要用于写入核心转储文件时，在这种情况下，工作进程应对指定的目录具有写权限。