Nginx 配置文件结构详解 | 方的代码随记

Nginx 配置文件的层级是 全局块 → events 块 → http 块 → server 块 → location 块，每个指令只能出现在允许的层级。

一、全局块

从配置文件开头到 events 之间的内容，影响 Nginx 服务器整体运行。

指令	说明	可配置层级
`user [user] [group]`	运行 Nginx 的用户和用户组。注释掉或配成 `nobody` 则所有用户可运行；Windows 上不生效	仅全局块
`worker_processes number \| auto`	工作线程数，生成一个 master 进程 + N 个 worker 进程	仅全局块
`pid logs/nginx.pid`	pid 文件存放路径	仅全局块
`error_log path [debug\|info\|notice\|warn\|error\|crit\|alert\|emerg]`	错误日志路径与级别，`debug` 需编译时加 `--with-debug`	全局、http、server、location
`worker_rlimit_nofile`	单个进程可打开的最大文件描述符数，建议与 `ulimit -n` 一致	仅全局块

二、events 块

影响 Nginx 与用户的网络连接。

指令	说明
`accept_mutex on \| off`	对多个进程接收连接做序列化，防止「惊群」，默认开启
`multi_accept on \| off`	是否允许一个 worker 同时接受多个新连接，默认 `off`
`use method`	指定网络 IO 模型：`select` / `poll` / `kqueue` / `epoll` / `rtsig` / `/dev/poll` / `eventport`。Linux 2.6+ 用 `epoll`，FreeBSD 用 `kqueue`
`worker_connections 1024`	每个 worker 同时开启的最大连接数。不能超过系统最大文件打开数，也不能超过单进程最大文件打开数

三、http 块

代理、缓存、日志定义等绝大多数功能和第三方模块配置都在这里，可包含多个 server 块。

指令	说明
`include mime.types`	引入 MIME 类型映射表。被 include 的文件必须符合所在层级的规范
`default_type application/octet-stream`	默认响应类型，默认是 `text/plain`
`access_log path [format [buffer=size]]`	访问日志，关闭用 `access_log off`
`log_format main ...`	定义日志格式，只能在 http 块配置
`sendfile on \| off`	是否使用 sendfile 零拷贝传输文件
`sendfile_max_chunk size`	每次 `sendfile()` 传输的最大数据量，`0` 表示无限制
`keepalive_timeout timeout [header_timeout]`	连接保持时间，默认 `75s`
`keepalive_requests number`	单连接请求数上限，默认 `100`

四、server 块（虚拟主机）

每个 server 块相当于一台虚拟主机，让一组 Nginx 进程对外提供多个站点。

listen 指令

只能在 server 块配置，默认值为 listen *:80 | *:8000。三种语法：

listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] ... ;
listen unix:path [default_server] [ssl] ... ;

示例：

listen 127.0.0.1:8000;   # 只监听 127.0.0.1 的 8000 端口
listen 127.0.0.1;        # 只监听 127.0.0.1，端口默认 80
listen 8000;             # 监听所有 IP 的 8000 端口
listen *:8000;           # 同上
listen localhost:8000;   # 同第一种

关键参数：

address：监听的 IP，IPv6 需用中括号，如 [fe80::1]；
port：端口，未定义则用 80。若完全不配置 listen，以超级用户运行时使用 *:80，否则 *:8000；
default_server：Host 未匹配到任何虚拟主机时由它处理；
backlog=number：listen() 允许同时挂起的最大连接数，FreeBSD 默认 -1，其他平台 511；
ssl：该连接使用 SSL 模式。

server_name 指令

server_name myserver.com www.myserver.com;   # 第一个为主要名称
server_name myserver.* *.myserver.com;       # 支持通配符

通配符只能用在三段名称的首段或尾段、两段名称的尾段，也支持正则表达式。多虚拟主机匹配到同一名称时的优先级：

准确匹配 server_name
通配符在开始时匹配成功
通配符在结尾时匹配成功
正则表达式匹配成功

同优先级下，首次匹配成功的虚拟主机处理请求。

五、location 块

location [ = | ~ | ~* | ^~ ] uri { ... }

匹配规则：

=：标准 uri 前，要求严格匹配，匹配成功立即处理；
^~：找到匹配度最高的标准 uri 后立即处理，不再做正则匹配；
~：uri 含正则表达式，区分大小写；
~*：uri 含正则表达式，不区分大小写。

默认行为：先在多个 location 中用标准 uri 匹配，记录匹配度最高的一个；再用正则 uri 匹配，第一个成功即结束；正则全失败则用前面记录的标准 uri 处理。

其他常用指令：

root path：请求寻找资源的根目录，可在 http / server / location 配置，通常放在 location；path 中可使用除 $document_root 和 $realpath_root 外的预设变量；
alias、index、error_page 同理按需配置。

六、完整配置样例（带注释）

# 定义 Nginx 运行的用户和用户组
user www www;

# 进程数，建议等于 CPU 总核心数
worker_processes 8;

# 全局错误日志定义类型
error_log /usr/local/nginx/logs/error.log info;

# 进程 pid 文件
pid /usr/local/nginx/logs/nginx.pid;

# 单个进程可打开的最大文件描述符数目，最好与 ulimit -n 保持一致
worker_rlimit_nofile 65535;

events {
    use epoll;
    worker_connections 65535;
    keepalive_timeout 60;

    # 客户端请求头缓冲区大小，建议设为系统分页大小的整数倍
    # 分页大小：getconf PAGESIZE
    client_header_buffer_size 4k;

    # 打开文件缓存：max 建议与打开文件数一致，inactive 为未被请求后删除缓存的时间
    open_file_cache max=65535 inactive=60s;
    open_file_cache_valid 80s;       # 多久检查一次缓存有效信息
    open_file_cache_min_uses 1;      # inactive 时间内最少使用次数
    open_file_cache_errors on;       # 是否记录 cache 错误
}

http {
    include mime.types;
    default_type application/octet-stream;
    # charset utf-8;

    server_names_hash_bucket_size 128;
    client_header_buffer_size 32k;
    large_client_header_buffers 4 64k;   # header 过大时使用
    client_max_body_size 8m;             # 上传文件大小上限

    sendfile on;         # 零拷贝传输，磁盘 IO 重负载场景可设 off
    autoindex on;        # 开启目录列表访问，默认关闭
    tcp_nopush on;       # 仅在使用 sendfile 时生效
    tcp_nodelay on;
    keepalive_timeout 120;

    # FastCGI 参数
    fastcgi_connect_timeout 300;
    fastcgi_send_timeout 300;
    fastcgi_read_timeout 300;
    fastcgi_buffer_size 64k;
    fastcgi_buffers 4 64k;
    fastcgi_busy_buffers_size 128k;
    fastcgi_temp_file_write_size 128k;

    # gzip 压缩
    gzip on;
    gzip_min_length 1k;
    gzip_buffers 4 16k;
    gzip_http_version 1.0;      # 前端是 squid 2.5 时用 1.0
    gzip_comp_level 2;
    gzip_types text/plain application/x-javascript text/css application/xml;
    gzip_vary on;

    # 负载均衡
    upstream backend {
        server 192.168.80.121:80 weight=3;
        server 192.168.80.122:80 weight=2;
        server 192.168.80.123:80 weight=3;
    }

    server {
        listen 80;
        server_name www.example.com example.com;
        index index.html index.htm index.php;
        root /data/www/example;

        location ~ .*\.(php|php5)?$ {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_index index.php;
            include fastcgi.conf;
        }

        location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$ {
            expires 10d;
        }

        location ~ .*\.(js|css)?$ {
            expires 1h;
        }
    }
}

upstream 的四种分配方式

方式	说明
轮询（默认）	按时间顺序逐一分配，后端 down 掉自动剔除
`weight`	权重越高被分配几率越大，用于后端性能不均
`ip_hash`	按访问 IP 的 hash 分配，可解决 session 问题
`fair` / `url_hash`（第三方）	按响应时间分配 / 按 URL hash 分配，后端为缓存服务器时有效

设备状态：down（不参与负载）、weight（权重）、max_fails（允许失败次数，默认 1）、fail_timeout（失败后暂停时间）、backup（其他机器忙时接管）。

Nginx 指令远不止这些，完整列表以官方文档为准。本文重点在于理清配置文件的结构。