Nginx配置文件解析-育师

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 上下文)

指令	语法 / 默认 / 上下文	说明
`user`	`user user [group];`/`nobody nobody`/main	Worker 进程运行身份。容器中常为`nginx`。Master 仍以 root 启动以便 bind 低端口。
`worker_processes`	`worker_processes number \| auto;`/`1`/main	Worker 进程数。`auto`= CPU 核心数,生产推荐。
`worker_cpu_affinity`	`auto [cpumask];`/ — /main	把 worker 绑定到指定 CPU 核心,降低上下文切换。
`worker_priority`	`-20..20`/`0`/main	Worker 进程 nice 优先级。
`worker_rlimit_nofile`	`worker_rlimit_nofile number;`/ — /main	单 worker 可打开文件描述符上限。建议 ≥`worker_connections`。
`worker_shutdown_timeout`	`time`/ — /main(1.11.11+)	优雅关闭最长等待时间。
`error_log`	`error_log file [level] [json];`/`logs/error.log error`/main, http, mail, stream, server, location	错误日志路径与级别。级别由低到高:`debug < info < notice < warn < error < crit < alert < emerg`。容器化可用`stderr`写到标准错误。
`pid`	`pid file;`/`logs/nginx.pid`/main	主进程 PID 文件位置。
`daemon`	`on \| off;`/`on`/main	是否以守护进程方式运行。容器内常设`off`。
`master_process`	`on \| off;`/`on`/main	是否启用 master/worker 模型(调试用)。
`env`	`env VAR[=VALUE];`/`env TZ;`/main	保留/设置传给 worker 的环境变量。
`include`	`include file \| mask;`/ — /任意上下文	引入外部配置。例:`include conf.d/*.conf;`
`load_module`	`load_module file;`/ — /main(1.9.11+)	动态加载模块。
`pcre_jit`	`on \| off;`/`off`/main	启用 PCRE JIT,显著加速正则匹配。
`thread_pool`	`name threads=N [max_queue=N];`/`default threads=32 max_queue=65536`/main	异步 I/O 线程池,配合`aio threads;`。
`timer_resolution`	`interval`/ — /main	内部时间缓存刷新粒度,减少`gettimeofday`调用。
`ssl_engine`	`device`/ — /main	硬件 SSL 加速器名称。
`working_directory`	`directory`/ — /main	core 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 { ... }`	— /main	HTTP 服务总入口。
`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	目录的默认索引文件。
<