Nginx 配置文件属性说明文档(基于官网 v1.27+)数据来源:Alphabetical index of directives及各模块手册。 本文档覆盖 Nginx 配置文件中最常用的全部属性,按"模块 → 上下文"的官方组织方式编排。0. 文档约定上下文(Context):指令允许出现的配置块层级,从外到内依次是:main(主上下文,即配置文件最外层)events、http、mail、stream(顶层模块块)server(虚拟主机)location(URI 路径匹配)if、limit_except、upstream、map等子上下文每条指令格式:Syntax | Default | Context | 说明1. 配置文件总体结构# main 上下文 user nginx; worker_processes auto; error_log logs/error.log notice; pid logs/nginx.pid; events { # events 上下文 worker_connections 1024; use epoll; } http { # http 上下文 include mime.types; default_type application/octet-stream; upstream backend { ... } # upstream 子上下文 server { # server(虚拟主机)上下文 listen 80; server_name example.com; location / { # location 子上下文 proxy_pass http://backend; } } } stream { ... } # 4 层 TCP/UDP 代理 mail { ... } # 邮件代理(很少用)继承规则:内层默认继承外层;但add_header、proxy_set_header、access_log等是"全部替换"语义——内层一旦写了任何一条,外层的全部失效,需要显式重写。2. Core 模块(ngx_core_module—— main 上下文)指令语法 / 默认 / 上下文说明useruser user [group];/nobody nobody/mainWorker 进程运行身份。容器中常为nginx。Master 仍以 root 启动以便 bind 低端口。worker_processesworker_processes number | auto;/1/mainWorker 进程数。auto= CPU 核心数,生产推荐。worker_cpu_affinityauto [cpumask];/ — /main把 worker 绑定到指定 CPU 核心,降低上下文切换。worker_priority-20..20/0/mainWorker 进程 nice 优先级。worker_rlimit_nofileworker_rlimit_nofile number;/ — /main单 worker 可打开文件描述符上限。建议 ≥worker_connections。worker_shutdown_timeouttime/ — /main(1.11.11+)优雅关闭最长等待时间。error_logerror_log file [level] [json];/logs/error.log error/main, http, mail, stream, server, location错误日志路径与级别。级别由低到高:debug info notice warn error crit alert emerg。容器化可用stderr写到标准错误。pidpid file;/logs/nginx.pid/main主进程 PID 文件位置。daemonon | off;/on/main是否以守护进程方式运行。容器内常设off。master_processon | off;/on/main是否启用 master/worker 模型(调试用)。envenv VAR[=VALUE];/env TZ;/main保留/设置传给 worker 的环境变量。includeinclude file | mask;/ — /任意上下文引入外部配置。例:include conf.d/*.conf;load_moduleload_module file;/ — /main(1.9.11+)动态加载模块。pcre_jiton | off;/off/main启用 PCRE JIT,显著加速正则匹配。thread_poolname threads=N [max_queue=N];/default threads=32 max_queue=65536/main异步 I/O 线程池,配合aio threads;。timer_resolutioninterval/ — /main内部时间缓存刷新粒度,减少gettimeofday调用。ssl_enginedevice/ — /main硬件 SSL 加速器名称。working_directorydirectory/ — /maincore dump 输出目录。3. Events 模块(events { ... })指令默认 / 上下文说明worker_connections number;512/events单 worker 最大并发连接。最大并发 ≈ workers × 此值。use method;自动 /events事件驱动:epoll(Linux)、kqueue(BSD/macOS)、eventport、/dev/poll、select、poll。multi_accept on | off;off/events一次 accept 多个连接。kqueue 下被忽略。accept_mutex on | off;off(1.11.3+) /events多 worker 顺序 accept,避免惊群。支持EPOLLEXCLUSIVE或reuseport时无需开。accept_mutex_delay time;500ms/events上一指令开启后的 accept 重试延迟。debug_connection address | CIDR;— /events仅对指定客户端记录 debug 日志(需--with-debug编译)。4. HTTP 核心模块(ngx_http_core_module)4.1 http 上下文常用指令指令默认 / 上下文说明http { ... }— /mainHTTP 服务总入口。server { ... }— /http, upstream定义虚拟主机或上游成员。default_type mime-type;text/plain/ http, server, location未匹配 mime 类型时的兜底。types { ... }见mime.types/ http, server, location后缀 → MIME 映射。keepalive_timeout time [header];75s/ http, server, location长连接保持时间。keepalive_requests number;1000(1.19.10+) / http, server, location单条长连接最多服务多少请求。keepalive_disable none | browser;msie6/ http, server, location禁用部分 UA 的 keep-alive。sendfile on | off;off/ http, server, location启用零拷贝静态文件下发。tcp_nopush on | off;off/ http, server, location配合 sendfile,合并小包。tcp_nodelay on | off;on/ http, server, location长连接下尽快发小包。client_body_buffer_size size;8k/16k / http, server, location请求体内存缓冲区。client_body_temp_path path ...;client_body_temp/ http, server, location请求体临时目录。client_body_timeout time;60s/ http, server, location读取请求体两次操作之间的最大间隔。client_header_buffer_size size;1k/ http, server请求行+请求头初始缓冲。client_header_timeout time;60s/ http, server读完整个请求头的超时。client_max_body_size size;1m/ http, server, location允许的最大请求体,超出返回 413。large_client_header_buffers N size;4 8k/ http, server大请求头的额外缓冲。send_timeout time;60s/ http, server, location向客户端写两次操作之间的最大间隔。reset_timedout_connection on | off;off/ http, server, location超时直接 RST 连接。server_tokens on | off | build | string;on/ http, server, location是否暴露 nginx 版本号。merge_slashes on | off;on/ http, server是否合并 URI 中重复/。underscores_in_headers on | off;off/ http, server允许请求头名含下划线。ignore_invalid_headers on | off;on/ http, server是否忽略不合法的请求头。chunked_transfer_encoding on | off;on/ http, server, location是否允许响应使用 chunked 编码。etag on | off;on/ http, server, location是否对静态资源生成 ETag。if_modified_since off | exact | before;exact/ http, server, location处理条件请求的方式。directio size | off;off/ http, server, location大文件绕过页缓存直接 I/O。aio on | off | threads[=pool];off/ http, server, location异步 I/O 启用。output_buffers N size;2 32k/ http, server, location磁盘读文件输出缓冲。4.2 server 块常用指令指令默认 / 上下文说明listen address[:port] [...];*:80/server监听端口。参数:default_server、ssl、http2、http3、reuseport、proxy_protocol、backlog=N。server_name name ...;""/server虚拟主机名,支持精确、通配*.x.com、正则~^...$、特殊值_。server_name_in_redirect on | off;off/ http, server, location重定向时使用 server_name 还是 Host。port_in_redirect on | off;on/ http, server, location重定向 URL 中是否带端口。absolute_redirect on | off;on/ http, server, location重定向使用绝对 URL 还是相对。root path;html/ http, server, location, if静态资源根目录。最终路径 =root+URI。alias path;— /location替换 location 前缀后的路径。与 root 拼接语义不同。index file ...;index.html/ http, server, location目录的默认索引文件。