nginx.conf 配置结构

学 Nginx 90% 的时间在学配置文件。Nginx 的配置虽然长得像代码，但其实只是一组嵌套的指令，没有循环、没有判断。这一章我们把主配置文件 nginx.conf 拆开看清楚，理解它的三层结构——这是后面所有章节的地基。

1. 配置文件在哪里？

不同系统下主配置文件的位置：

• Ubuntu / Debian：/etc/nginx/nginx.conf
• CentOS / RHEL：/etc/nginx/nginx.conf（与 Ubuntu 一致）
• Mac Homebrew（Intel）：/usr/local/etc/nginx/nginx.conf
• Mac Homebrew（Apple Silicon）：/opt/homebrew/etc/nginx/nginx.conf
• 源码编译：默认在 /usr/local/nginx/conf/nginx.conf，可用 -prefix 改
• 测试某个非默认配置：nginx -c /path/to/nginx.conf

下面所有讨论都以 Linux 下的 /etc/nginx/nginx.conf 为准。

2. 完整的主配置文件长什么样

下面是一份带详细注释的 nginx.conf 全貌，建议通读一遍，先建立整体印象：

# /etc/nginx/nginx.conf — 主配置文件全貌
# 井号开头是注释

# ========== 1. 全局块（main）==========
user  www-data;                 # worker 进程以哪个用户身份运行
worker_processes  auto;         # worker 数量，auto = 自动等于 CPU 核数
error_log  /var/log/nginx/error.log warn;   # 错误日志路径与级别
pid    /var/run/nginx.pid;      # PID 文件位置

# ========== 2. events 块 ==========
events {
    worker_connections  1024;   # 每个 worker 能处理的最大连接数
    # use epoll;                # 事件模型（Linux 默认就是 epoll，一般不用显式写）
    multi_accept on;            # 一次接受所有新连接（默认 off）
}

# ========== 3. http 块 ==========
http {
    include       /etc/nginx/mime.types;   # 文件类型映射表
    default_type  application/octet-stream; # 默认 Content-Type

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent"';          # 日志格式定义

    access_log  /var/log/nginx/access.log  main;     # 访问日志

    sendfile        on;          # 启用零拷贝（静态文件加速）
    tcp_nopush      on;          # 等数据包填满再发（配合 sendfile）
    keepalive_timeout  65;       # 长连接超时（秒）

    # gzip 压缩（下一篇压缩章节会详细讲）
    gzip  on;

    # ========== 4. server 块（虚拟主机）==========
    server {
        listen       80;                   # 监听端口
        server_name  localhost;            # 域名
        location / {
            root   /usr/share/nginx/html;  # 网站根目录
            index  index.html index.htm;   # 默认首页
        }
        error_page  404 /404.html;         # 404 时跳转到 /404.html
    }

    # 加载 conf.d 下的所有站点配置（推荐在这里加自己的 server）
    include /etc/nginx/conf.d/*.conf;
}

看起来很长，其实就三大块：全局块 → events 块 → http 块。http 块里又嵌套 server 块，server 块里再嵌套 location 块。

3. 三层结构详解

第一层：全局块（main）

配置文件开头到 events 块之前的所有指令，影响 Nginx 整体行为：

• user：worker 进程的运行用户（影响文件读写权限）。
• worker_processes：worker 数量，建议设为 CPU 核数（auto 自动）。
• error_log：错误日志的位置和级别（debug/info/notice/warn/error/crit）。
• pid：master 进程的 PID 文件位置。
• worker_rlimit_nofile：worker 能打开的最大文件描述符数（高并发必调）。

第二层：events 块

影响 Nginx 服务器与用户的网络连接。最关键的指令是 worker_connections——它决定每个 worker 能同时处理多少连接。

最大并发连接数 = worker_processes × worker_connections。比如 4 核 CPU + 1024 连接，理论最大 4096 并发。生产环境通常调到 10240 甚至更高。

第三层：http 块

这是配置的主体，所有 HTTP/Web 服务相关的功能都在这里配置。它可以包含：

• 全局 HTTP 指令：sendfile、keepalive_timeout、gzip 等。
• 文件类型映射：include /etc/nginx/mime.types。
• 日志格式：log_format + access_log。
• 若干 server 块：每个 server 是一个虚拟主机。
• include /etc/nginx/conf.d/*.conf：把外部站点配置文件拉进来。

4. server 块与 location 块（先扫一眼）

server 块代表一个虚拟主机，location 块代表 URL 的匹配规则——它们是后面两章的主角。这里先记住嵌套关系即可：

• 一个 http 块可以包含多个 server 块；
• 一个 server 块可以包含多个 location 块；
• 指令越靠近内层，作用域越小。

5. 指令的两种类型与继承规则

Nginx 配置指令分两类：

# 指令分两类：简单指令 和 块指令
# 简单指令：名字 + 参数 + 分号
worker_processes auto;
listen 80;

# 块指令：名字 + 参数 + 一组用花括号包裹的子指令
events {
    worker_connections 1024;
}

# 块指令可以嵌套块指令
http {
    server {
        location / {
            root /var/www;
        }
    }
}

# 继承规则：子块继承父块的指令，但子块里重新定义会覆盖父块
http {
    server_tokens off;        # 对所有 server 生效
    server {
        server_tokens on;     # 仅本 server 生效（覆盖了 http 层）
    }
}

继承规则：子块自动继承父块的指令值，但在子块内重新定义会覆盖父块的值。一条经验法则：能放外层就放外层，避免重复。

6. include：拆分配置的利器

生产环境的 Nginx 配置往往几百上千行，全部塞进 nginx.conf 难以维护。include 指令可以把另一个文件的内容"粘贴"到当前位置——这是组织配置的核心手段：

# include 指令：把另一个文件的内容"粘贴"到当前位置
# 好处：把长配置拆成多个小文件，便于管理

# 主配置 nginx.conf 里常见这两行
http {
    include /etc/nginx/mime.types;       # 引入 MIME 类型映射
    include /etc/nginx/conf.d/*.conf;    # 引入所有站点配置（通配符）
}

# 站点配置放在 /etc/nginx/conf.d/mysite.conf
server {
    listen 80;
    server_name mysite.com;
    root /var/www/mysite;
}

# 重载配置即可生效
sudo nginx -t && sudo nginx -s reload

推荐做法：永远不要直接改 nginx.conf 主文件！把自己的站点配置放到 /etc/nginx/conf.d/<name>.conf，主配置里已经默认 include 了这些文件。

7. 常用指令速查表

把这些指令记住，90% 的配置任务都能搞定：

# 全局块常用指令
user www-data;              # worker 运行用户
worker_processes auto;      # worker 数（auto 等于 CPU 核数）
worker_rlimit_nofile 65535; # 每个 worker 能打开的最大文件描述符数
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

# events 块常用指令
events {
    worker_connections 1024;     # 每个 worker 最大连接数
    multi_accept on;             # 同时接受多个新连接
    use epoll;                   # 显式指定事件模型（一般不用）
}

# http 块常用指令
http {
    sendfile on;                 # 零拷贝
    tcp_nopush on;
    keepalive_timeout 65;
    client_max_body_size 20m;    # 限制请求体大小（上传文件相关）
    server_tokens off;           # 隐藏 Nginx 版本号（安全）

8. 配置测试与排错

修改配置后，永远先测试再重载，这是 Nginx 工程师的肌肉记忆：

• sudo nginx -t — 测试配置语法，输出错误的具体行号。
• sudo nginx -T — 把所有 include 后的最终配置打印出来（调试利器）。
• sudo nginx -s reload — 平滑重载。
• 出错时看 /var/log/nginx/error.log。

一个常见坑：nginx -t 显示成功但 reload 后行为不对，多半是指令放错了层级（比如把 server 块指令写到了 http 块里）。用 nginx -T 看最终合并的配置就能发现。

小结

这一章你了解了 nginx.conf 的三层结构（全局 → events → http）、指令的继承规则、include 的用法。下一篇我们深入 server 块，学习如何配置一个虚拟主机——让一台机器同时服务多个域名。

← 上一篇 Nginx 安装

下一篇 server 块与虚拟主机 →