核心功能

示例配置
指令
     accept_mutex
     accept_mutex_delay
     daemon
     debug_connection
     debug_points
     env
     error_log
     events
     include
     load_module
     lock_file
     master_process
     multi_accept
     pcre_jit
     pid
     ssl_engine
     ssl_object_cache_inheritable
     thread_pool
     timer_resolution
     use
     user
     worker_aio_requests
     worker_connections
     worker_cpu_affinity
     worker_priority
     worker_processes
     worker_rlimit_core
     worker_rlimit_nofile
     worker_shutdown_timeout
     working_directory

示例配置

user www www;
worker_processes 2;

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

events {
    use kqueue;
    worker_connections 2048;
}

...

指令

语法 accept_mutex on | off;
默认值
accept_mutex off;
上下文 events

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

在支持 EPOLLEXCLUSIVE 标志 (1.11.3) 的系统上或使用 reuseport 时,无需启用 accept_mutex

在 1.11.3 版本之前,默认值是 on

语法 accept_mutex_delay 时间;
默认值
accept_mutex_delay 500ms;
上下文 events

如果启用了 accept_mutex,此指令指定了当其他工作进程正在接受新连接时,工作进程尝试重新开始接受新连接的最长时间。

语法 daemon on | off;
默认值
daemon on;
上下文 main

决定 nginx 是否应作为守护进程运行。主要用于开发期间。

语法 debug_connection 地址 | CIDR | unix:;
默认值
上下文 events

为选定的客户端连接启用调试日志。其他连接将使用 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;
默认值
上下文 main

此指令用于调试。

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

语法 env 变量[=];
默认值
env TZ;
上下文 main

默认情况下,nginx 会移除从父进程继承的所有环境变量,除了 TZ 变量。此指令允许保留一些继承的变量、更改它们的值或创建新的环境变量。然后这些变量会

除非明确配置,否则 TZ 变量总是被继承并可供 ngx_http_perl_module 模块使用。

使用示例

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

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

语法 error_log 文件 [级别];
默认值
error_log logs/error.log error;
上下文 main, http, mail, stream, server, location

配置日志记录。可以在同一配置级别 (1.5.2) 指定多个日志。如果在 main 配置级别未明确定义日志文件写入,则使用默认文件。

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

第二个参数确定日志的 级别,可以是以下之一: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 级别指定。

语法 events { ... }
默认值
上下文 main

提供配置文件上下文,其中指定了影响连接处理的指令。

语法 include 文件 | 掩码;
默认值
上下文 any

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

使用示例

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

语法 load_module 文件;
默认值
上下文 main

此指令出现在 1.9.11 版本中。

加载动态模块。

示例

load_module modules/ngx_mail_module.so;

语法 lock_file 文件;
默认值
lock_file logs/nginx.lock;
上下文 main

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

语法 master_process on | off;
默认值
master_process on;
上下文 main

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

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

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

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

语法 pcre_jit on | off;
默认值
pcre_jit off;
上下文 main

此指令出现在 1.1.12 版本中。

为配置解析时已知的正则表达式启用或禁用“即时编译”(PCRE JIT)。

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

JIT 在 PCRE 库 8.20 版本及更高版本中可用,需要使用 --enable-jit 配置参数构建。当 PCRE 库与 nginx 一起构建时 (--with-pcre=),通过 --with-pcre-jit 配置参数启用 JIT 支持。

语法 pid 文件;
默认值
pid logs/nginx.pid;
上下文 main

定义一个 文件,用于存储主进程的进程 ID。

语法 ssl_engine 设备;
默认值
上下文 main

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

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

语法 ssl_object_cache_inheritable on | off;
默认值
ssl_object_cache_inheritable on;
上下文 main

此指令出现在 1.27.4 版本中。

如果启用,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;
    }
}

语法 thread_pool 名称 threads=数量 [max_queue=数量];
默认值
thread_pool default threads=32 max_queue=65536;
上下文 main

此指令出现在 1.7.11 版本中。

定义用于不阻塞工作进程的多线程文件读写操作的线程池的 名称 和参数。

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

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

语法 timer_resolution 间隔;
默认值
上下文 main

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

示例

timer_resolution 100ms;

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

语法 use 方法;
默认值
上下文 events

指定要使用的连接处理 方法。通常无需明确指定,因为 nginx 默认会使用最有效的方法。

语法 user 用户 [];
默认值
user nobody nobody;
上下文 main

定义工作进程使用的 用户 凭据。如果省略 ,则使用与 用户 同名的组。

语法 worker_aio_requests 数量;
默认值
worker_aio_requests 32;
上下文 events

此指令出现在 1.1.4 和 1.0.7 版本中。

当将 aioepoll 连接处理方法一起使用时,设置单个工作进程的最大未完成异步 I/O 操作 数量

语法 worker_connections 数量;
默认值
worker_connections 512;
上下文 events

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

应该注意的是,这个数字包括所有连接(例如与代理服务器的连接等),而不仅仅是与客户端的连接。另一个考虑因素是,实际的并发连接数不能超过当前对最大打开文件数的限制,该限制可以通过 worker_rlimit_nofile 更改。

语法 worker_cpu_affinity cpu掩码 ...;
worker_cpu_affinity auto [cpu掩码];
默认值
上下文 main

将工作进程绑定到 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 数值;
默认值
worker_priority 0;
上下文 main

定义工作进程的调度优先级,就像 nice 命令所做的那样:负值 数值 表示更高的优先级。允许的范围通常在 -20 到 20 之间。

示例

worker_priority -10;

语法 worker_processes 数量 | auto;
默认值
worker_processes 1;
上下文 main

定义工作进程的数量。

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

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

语法 worker_rlimit_core 大小;
默认值
上下文 main

更改工作进程核心文件最大大小 (RLIMIT_CORE) 的限制。用于在不重启主进程的情况下提高限制。

语法 worker_rlimit_nofile 数量;
默认值
上下文 main

更改工作进程最大打开文件数 (RLIMIT_NOFILE) 的限制。用于在不重启主进程的情况下提高限制。

语法 worker_shutdown_timeout 时间;
默认值
上下文 main

此指令出现在 1.11.11 版本中。

配置工作进程优雅关闭的超时时间。当 时间 到期时,nginx 将尝试关闭所有当前打开的连接以促进关闭。

语法 working_directory 目录;
默认值
上下文 main

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