Nginx 完整配置全复习（主配置 + 模块详解 + 实战模板 + 常见坑）

默认文件路径：/etc/nginx/nginx.conf（主配置），站点配置一般放 conf.d/*.conf
语法校验：nginx -t；重载：nginx -s reload；停止：nginx -s stop

一、Nginx 配置整体层级结构（从上到下作用域）

main（全局块）
├── events {} 事件模块
├── http {}  HTTP核心模块
│   ├── server {} 虚拟主机（站点）
│   │   ├── location {} 路由匹配
│   │   ├── if / rewrite / error_page 等
│   ├── upstream {} 负载均衡（http块内，server块外）
│   ├── include 引入子配置

二、逐块完整配置讲解（附带可直接运行样板）

1. 全局块 main（最外层，不属于任何大括号）

# 运行worker进程的用户，linux推荐nginx，不要root
user nginx;

# worker进程数量，auto=CPU核心数，生产建议等于CPU核心
worker_processes auto;

# 指定错误日志路径，级别：debug|info|notice|warn|error|crit
error_log /var/log/nginx/error.log warn;

# 进程PID文件
pid /var/run/nginx.pid;

# 文件描述符最大打开数（单个worker）
worker_rlimit_nofile 65535;

2. events {} 事件模块（网络 IO 模型）

events {
    # 使用epoll模型（linux专用；freebsd用kqueue）
    use epoll;

    # 每个worker最大同时连接数
    worker_connections 10240;

    # 开启多路复用，尽可能一次接收多个连接
    multi_accept on;
}

理论最大并发连接上限 = worker_processes × worker_connections

3. http {} 块（HTTP 服务全局通用配置，所有 server 继承）

http {
    # ---------------- 文件mime类型映射 ----------------
    include /etc/nginx/mime.types;
    default_type application/octet-stream; # 未知文件默认二进制下载

    # ---------------- 日志格式 ----------------
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log main;

    # ---------------- 性能优化 ----------------
    sendfile on; # 零拷贝发送文件，静态文件必备
    tcp_nopush on; # 合并数据包，配合sendfile
    tcp_nodelay on; # 长连接小包立即发送

    # keepalive 长连接超时
    keepalive_timeout 65;
    keepalive_requests 100; # 一条长连接最多请求次数

    # 开启gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_vary on;

    # 隐藏nginx版本号（安全优化）
    server_tokens off;

    # 上传文件最大大小
    client_max_body_size 10M;
    # 请求头、请求体超时
    client_header_timeout 10s;
    client_body_timeout 10s;
    send_timeout 30s;

    # 引入所有站点配置
    include /etc/nginx/conf.d/*.conf;
}

4. upstream {} 负载均衡（定义后端集群，放在 http 内、server 外）

基础模板

upstream backend_server {
    # 轮询（默认）
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;

    # weight 权重模式
    # server 127.0.0.1:8080 weight=3;
    # server 127.0.0.1:8081 weight=1;

    # ip_hash 会话保持（客户端ip固定分到同一台）
    # ip_hash;

    # fair 按后端响应时间分配（第三方模块nginx-upstream-fair）

    # 参数说明
    # backup 备用节点；down 下线节点
    # **max_fails 最大失败次数；fail_timeout 故障探测时间**
    # server 127.0.0.1:8082 backup;
}

upstream backend_server {
    # 轮询（默认）
    server 127.0.0.1:8080 max_fails=2 fail_timeout=30s;
    server 127.0.0.1:8081 backup;
}
逻辑时序：
主故障，连续 2 次失败 → 标记主不可用，持续 30s → 流量切 backup
主服务重启恢复，但是 Nginx 还标记主不可用，接下来 30s 依旧走 backup
30s fail_timeout 计时结束，新请求过来，Nginx 尝试访问主
如果主健康，标记主恢复，流量切回主，backup 不再使用。

5. server {} 虚拟主机（一个站点，http 块内）

监听端口、域名、证书、全局响应规则

请求头透传

proxy_set_header Host $host;：把原始请求 Host 传给后端，后端用来处理域名、Cookie、跳转
proxy_set_header X-Real-IP $remote_addr;：真实客户端 IP
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;：代理链 IP 列表，后端日志拿真实访客 IP

server {
    listen 80;                # 监听ipv4 80端口
    # listen [::]:80;         # 监听ipv6
    server_name www.test.com test.com; # 绑定域名，空格分隔

    # http强制跳转https
    return 301 https://$host$request_uri;
}

# HTTPS站点完整示例
server {
    listen 443 ssl;
    server_name www.test.com test.com;

    # ssl证书
    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    # ssl安全套件
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 访问日志（可以单独站点独立日志）
    access_log /var/log/nginx/test.access.log main;
    error_log /var/log/nginx/test.error.log warn;

    # 错误页面
    error_page 404 /404.html;
    error_page 500 502 503 504 /5xx.html;

    # ================= location 路由匹配核心 =================
    # location 匹配优先级：
    # 1. = 精确匹配 > 2. ^~ 前缀匹配 > 3. ~ ~*正则 > 4. 普通前缀匹配
    # ~ 区分大小写正则；~* 不区分大小写

    # 精确匹配首页
    location = / {
        root /data/www;
        index index.html index.htm;
    }

    # 静态资源缓存（图片、js、css）
    location ~* \.(jpg|png|gif|ico|css|js)$ {
        root /data/www;
        expires 7d;       # 浏览器缓存7天
        add_header Cache-Control "public";
    }

    # 反向代理到后端服务
    location /api/ {
        proxy_pass http://backend_server; # 对应upstream集群
        # 代理头传递（非常关键！后端获取真实IP、域名）
        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;

        # 代理超时设置
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 禁止访问隐藏文件 .开头
    location ~ /\. {
        deny all;
    }

    # 根路径兜底
    location / {
        root /data/www;
        index index.html;
        try_files $uri $uri/ /index.html; # Vue/React SPA单页面必备！
    }
}

三、核心常用指令专项复习

1. root vs alias（高频面试考点）

# root：拼接路径 root + location路径
location /static/ {
    root /data/www;
    # 访问 /static/a.jpg → /data/www/static/a.jpg
}

# alias：直接替换location路径
location /static/ {
    alias /data/static/;
    # 访问 /static/a.jpg → /data/static/a.jpg
}
⚠️ alias 末尾目录务必带 /，容易403/404

2. rewrite 重写规则

语法：rewrite 正则目标 [flag];
flag：

last：重写后重新匹配 location（内部跳转）
break：停止匹配，不再查找 location
redirect：302 临时重定向
permanent：301 永久重定向

示例：

# 旧地址跳转新地址
rewrite ^/old/(.*)$ /new/$1 permanent;

3. if 判断（慎用！if 在 location 内有坑）

常用内置变量（高频）

$host 请求域名
$request_uri 完整请求uri（带参数）
$uri 当前uri
$remote_addr 客户端ip
$http_user_agent 浏览器UA
$http_referer 来源地址
$scheme http/https

示例：防盗链

location ~* \.(png|jpg)$ {
    valid_referers none blocked test.com *.test.com;
    if ($invalid_referer) {
        return 403;
    }
}

四、正向代理 vs 反向代理区别

正向代理：代理客户端（FQ代理），nginx 很少做
反向代理：代理服务端（用户访问 nginx，nginx 转发后端）
指令：proxy_pass 反向代理；resolver 正向代理

五、常用模块补充

stub_status 监控连接状态

location = /nginx-status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

访问看到：连接数、活跃连接、读写请求

limit_req 限流（漏桶）

http {
    limit_req_zone $binary_remote_addr zone=req_limit:10m rate=10r/s;
}
location / {
    limit_req zone=req_limit burst=20 nodelay;
}

limit_conn 连接数限制

limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
location / {
    limit_conn conn_limit 20;
}

六、调试命令清单（必须熟记）

# 检查配置语法
nginx -t
# 测试配置并打印详细
nginx -T

# 平滑重载（不中断连接）
nginx -s reload
# 快速停止
nginx -s stop
# 优雅停止（处理完现有连接再关闭）
nginx -s quit

# 查看nginx编译模块
nginx -V

七、常见踩坑清单（复习重点）

proxy_pass 末尾有无 / 路径差异

location /api/ {
    proxy_pass http://127.0.0.1:8080;      # /api/xxx → /api/xxx
    proxy_pass http://127.0.0.1:8080/;     # /api/xxx → /xxx
}

SPA 项目缺少 try_files 刷新页面 404
未配置 X-Forwarded-For，后端拿不到真实客户端 IP
ssl 证书路径权限不足导致启动失败
worker_rlimit_nofile < worker_connections 引发 too many open files
gzip 作用域放在 location 不生效，一般放在 http/server
location 正则顺序问题，长正则放前面

下一步我们可以按需深入：

我可以把上面所有内容合并成一份完整可直接部署的 nginx.conf 样板你直接复制测试
或者开始刷题：nginx 面试题（location 优先级、root/alias、proxy_pass、限流、负载均衡）
或者单独拆解某个难点（rewrite 规则、lua 模块、nginx+keepalived 高可用、ingress-nginx）

你想先进行哪一部分？

（注：部分内容可能由 AI 生成）

posted @ 2026-10-14 15:16 阿砖阅读(5) 评论(0) 收藏举报

刷新页面返回顶部

Nginx 完整配置全复习（主配置 + 模块详解 + 实战模板 + 常见坑）

Nginx 完整配置全复习（主配置 + 模块详解 + 实战模板 + 常见坑）

Nginx 完整配置全复习（主配置 + 模块详解 + 实战模板 + 常见坑）

一、Nginx 配置整体层级结构（从上到下作用域）

二、逐块完整配置讲解（附带可直接运行样板）

1. 全局块 main（最外层，不属于任何大括号）

2. events {} 事件模块（网络 IO 模型）

3. http {} 块（HTTP 服务全局通用配置，所有 server 继承）

4. upstream {} 负载均衡（定义后端集群，放在 http 内、server 外）

基础模板

5. server {} 虚拟主机（一个站点，http 块内）

三、核心常用指令专项复习

1. root vs alias（高频面试考点）

2. rewrite 重写规则

3. if 判断（慎用！if 在 location 内有坑）

四、正向代理 vs 反向代理区别

五、常用模块补充

六、调试命令清单（必须熟记）

七、常见踩坑清单（复习重点）

下一步我们可以按需深入：

公告