nginx配置文件

一、配置文件的“语法格式”与“书写铁律”

Nginx 配置是声明式、层级化的文本，不是编程语言。掌握 3 条铁律即可避开 90% 的语法错误：

规则 说明 正确示例 错误示例
指令以 ; 结尾 所有单行指令必须加分号，漏写直接 nginx -t 报错 gzip on; gzip on
块指令用 {} 包裹 块本身不加分号，内部指令逐行写 http { ... } http { ... };
注释用 # 仅支持单行注释，不支持 /* */ # 这是注释 /* 注释 */

📌 核心概念：上下文（Context）
每个指令都有生效范围，不能随意乱放。例如 listen 只能写在 server 块里，写在 http 或 location 块里会直接报错。Nginx 启动时会按层级合并配置。

二、Nginx 配置的 6 大上下文（层级结构）

配置文件像一棵树，从上到下依次是：

1
2
3
4
5
6
7
main（全局）
 └─ events（网络连接）
 └─ http（HTTP协议）
      ├─ upstream（后端服务器池）
      ├─ server（虚拟主机/一个网站）
      │    └─ location（URL路由与处理逻辑）
      └─ include（引入其他文件）

👉 记忆口诀：全局管进程 → events管连接 → http管协议 → server管域名 → location管路径

三、核心关键字/指令详解（按层级+作用+用法）

🔹 1. main 全局块（控制 Nginx 主进程）

关键字 作用 用法示例 说明
user 指定工作进程运行的用户/组 user www-data; 默认 nginx，静态目录需对该用户开放读权限
worker_processes 工作进程数 worker_processes auto; auto 自动匹配 CPU 核心数，生产环境必设
error_log 全局错误日志 error_log /var/log/nginx/error.log warn; 级别：debug/info/notice/warn/error/crit
pid 主进程 PID 文件路径 pid /run/nginx.pid; 用于 systemctl 或 kill 精准控制进程

🔹 2. events 块（控制网络连接能力）

关键字 作用 用法示例 说明
worker_connections 单个 worker 最大并发连接数 worker_connections 1024; 实际最大并发 = worker_processes × worker_connections
multi_accept 是否一次性接受多个新连接 multi_accept on; 高并发场景建议开启
use 事件驱动模型 use epoll; Linux 默认 epoll，性能最佳，通常无需手动写

🔹 3. http 块（HTTP 协议全局配置）

| 关键字 | 作用 | 用法
为了让你彻底掌握 Nginx 配置文件的写法，我们直接按“语法格式 → 上下文层级 → 核心关键字 → 变量系统 → 实战拆解”的逻辑展开。内容直击本质，避开冗长理论。

一、配置文件的“语法格式”与“书写铁律”

Nginx 配置是声明式、层级化的文本，不是编程语言。掌握 3 条铁律即可避开 90% 的语法错误：

规则 说明 正确示例 错误示例
指令以 ; 结尾 所有单行指令必须加分号，漏写直接 nginx -t 报错 gzip on; gzip on
块指令用 {} 包裹 块本身不加分号，内部指令逐行写 http { ... } http { ... };
注释用 # 仅支持单行注释，不支持 /* */ # 这是注释 /* 注释 */

📌 核心概念：上下文（Context）
每个指令都有生效范围，不能随意乱放。例如 listen 只能写在 server 块里，写在 http 或 location 块里会直接报错。Nginx 启动时会按层级合并配置。

二、Nginx 配置的 6 大上下文（层级结构）

配置文件像一棵树，从上到下依次是：

1
2
3
4
5
6
7
main（全局）
 └─ events（网络连接）
 └─ http（HTTP协议）
      ├─ upstream（后端服务器池）
      ├─ server（虚拟主机/一个网站）
      │    └─ location（URL路由与处理逻辑）
      └─ include（引入其他文件）

👉 记忆口诀：全局管进程 → events管连接 → http管协议 → server管域名 → location管路径

三、核心关键字/指令详解（按层级+作用+用法）

🔹 1. main 全局块（控制 Nginx 主进程）

关键字 作用 用法示例 说明
user 指定工作进程运行的用户/组 user www-data; 默认 nginx，静态目录需对该用户开放读权限
worker_processes 工作进程数 worker_processes auto; auto 自动匹配 CPU 核心数，生产环境必设
error_log 全局错误日志 error_log /var/log/nginx/error.log warn; 级别：debug/info/notice/warn/error/crit
pid 主进程 PID 文件路径 pid /run/nginx.pid; 用于 systemctl 或 kill 精准控制进程

🔹 2. events 块（控制网络连接能力）

关键字 作用 用法示例 说明
worker_connections 单个 worker 最大并发连接数 worker_connections 1024; 实际最大并发 = worker_processes × worker_connections
multi_accept 是否一次性接受多个新连接 multi_accept on; 高并发场景建议开启
use 事件驱动模型 use epoll; Linux 默认 epoll，性能最佳，通常无需手动写

🔹 3. http 块（HTTP 协议全局配置）

关键字 作用 用法示例 说明
include mime.types 加载文件 MIME 类型映射 include /etc/nginx/mime.types; 让浏览器知道 .js 是 application/javascript
default_type 未知文件类型的默认响应类型 default_type application/octet-stream; 防止浏览器直接下载未知类型文件
sendfile 启用零拷贝传输 sendfile on; 静态文件传输提速 30%+，必开
tcp_nopush / tcp_nodelay 优化 TCP 数据包合并/即时发送 tcp_nopush on; tcp_nodelay on; 配合 sendfile 使用，减少网络延迟
keepalive_timeout HTTP 长连接保持时间 keepalive_timeout 65; 单位秒，设为 0 关闭长连接
gzip 开启响应体压缩 gzip on; 节省 60%+ 带宽，移动端提速明显
gzip_types 指定压缩的文件类型 gzip_types text/css application/json; 默认只压缩 text/html，需手动加类型
include 引入外部配置文件 include /etc/nginx/conf.d/*.conf; 生产环境强烈建议按站点拆分配置

🔹 4. server 块（定义一个虚拟主机/网站）

关键字 作用 用法示例 说明
listen 监听端口/协议 listen 80; listen 443 ssl http2; 可加 default_server 作为未匹配域名时的兜底
server_name 绑定域名 server_name example.com www.example.com; 支持 *.example.com、~^www\d+\.example\.com$
root 站点根目录 root /var/www/html; 会被 location 继承，路径拼接规则见下方
index 默认首页文件 index index.html index.htm; 按顺序查找，第一个存在的文件生效
access_log 访问日志路径 access_log /var/log/nginx/access.log; 可关闭：access_log off;（不推荐）
error_page 自定义错误页 error_page 404 /404.html; 路径相对于 root，或写绝对 URL

🔹 5. location 块（URL 路由与处理逻辑，最核心）

关键字 作用 用法示例 说明
location [修饰符] 路径 { } 匹配请求 URI 并定义处理规则 location /api/ { ... } 修饰符决定匹配优先级（见后文）
proxy_pass 反向代理目标地址 proxy_pass http://127.0.0.1:3000; 末尾有无 / 决定路径拼接规则（高频坑）
proxy_set_header 向透传请求添加/修改头 proxy_set_header Host $host; 必加 X-Real-IP、X-Forwarded-For 否则后端拿不到真实 IP
try_files 尝试查找文件，失败则 fallback try_files $uri $uri/ /index.html; Vue/React 历史路由防 404 核心指令
root vs alias 静态文件路径映射 root /data/www; alias /data/img/; root 会拼接 location 路径，alias 会替换路径
expires / add_header 浏览器缓存控制 expires 30d; add_header Cache-Control "public"; 静态资源必配，大幅降低服务器负载
deny / allow IP 访问控制 allow 192.168.1.0/24; deny all; 按顺序匹配，最后一条生效，常用于后台限流

🔹 6. upstream 块（负载均衡池，供 proxy_pass 调用）

关键字 作用 用法示例 说明
server 定义后端节点 server 10.0.0.1:8080 weight=3; weight 权重，max_fails 失败阈值，backup 备用
ip_hash 按客户端 IP 哈希分配 ip_hash; 保证同一 IP 固定打到同一台后端（解决 Session 丢失）
least_conn 最少连接数分配 least_conn; 自动将请求发给当前连接数最少的服务器

四、Nginx 内置变量（配置的“动态血液”）

Nginx 配置不是死板的，大量指令支持 $变量名 动态替换。常用变量：

变量 含义 典型用法
$host 请求头中的 Host 字段（域名） proxy_set_header Host $host;
$remote_addr 客户端真实 IP proxy_set_header X-Real-IP $remote_addr;
$proxy_add_x_forwarded_for 追加代理链 IP proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
$scheme 请求协议（http 或 https） proxy_set_header X-Forwarded-Proto $scheme;
$request_uri 完整原始 URI（含参数） rewrite ^ /new$uri permanent;
$uri 解码后的 URI（不含参数） try_files $uri $uri/ /index.html;
$arg_name 获取 URL 中 ?name=xxx 的值 if ($arg_token = "") { return 401; }

五、完整配置逐行解析（看懂一套标准配置）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 1. 全局块
user www-data;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

# 2. 网络连接块
events {
    worker_connections 1024;
    multi_accept on;
}

# 3. HTTP 协议块
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    gzip on;
    gzip_types text/plain application/javascript text/css application/json;

    # 引入站点配置（生产环境推荐）
    include /etc/nginx/conf.d/*.conf;
}

对应站点配置 /etc/nginx/conf.d/app.conf：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# 4. 负载均衡池
upstream backend {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

# 5. 虚拟主机
server {
    listen 80;
    server_name api.example.com;
    root /var/www/app/public;
    index index.html;

    access_log /var/log/nginx/api_access.log;
    error_log  /var/log/nginx/api_error.log;

    # 6. 路由规则 1：静态资源
    location ~* \.(css|js|png|jpg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 7. 路由规则 2：反向代理 API
    location /api/ {
        proxy_pass http://backend;          # 无斜杠，完整转发
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 8. 路由规则 3：前端 SPA 兜底
    location / {
        try_files $uri $uri/ /index.html;
    }
}

六、编写与排错核心技巧（避坑指南）

场景 正确写法 错误写法/后果
proxy_pass 路径控制 location /api/ { proxy_pass http://b/; } → /api/x → /x 不加 / 会带 /api/ 转发，后端 404
root vs alias location /img/ { alias /data/pics/; } → /img/a.jpg → /data/pics/a.jpg 混用会导致路径错乱，图片 404
Location 优先级 = / > ^~ /path > ~ regex > ~* regex > /path 把正则写在前会拦截精确路径，路由失效
改配置生效 nginx -t → systemctl reload nginx 直接 restart 会断开现有连接，生产大忌
查看最终配置 nginx -T 手动找 include 容易遗漏覆盖关系

🛠️ 调试三步法

  1. sudo nginx -t：90% 的语法错误在此拦截
  2. tail -f /var/log/nginx/error.log：看 502/504/权限/路径错误详情
  3. curl -I http://127.0.0.1:端口/路径：验证响应头、跳转、代理是否生效
[up主专用，视频内嵌代码贴在这]