Nginx 核心配置结构：从 nginx.conf 到指令上下文

# 全局块：main 上下文
user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log  notice;
pid        /var/run/nginx.pid;

# events 上下文：网络模型
events {
    worker_connections  1024;
}

# http 上下文：HTTP 服务
http {
    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;
    keepalive_timeout  65;

    # server 上下文：虚拟主机
    server {
        listen       80;
        server_name  example.com;
        location / {
            root   /usr/share/nginx/html;
            index  index.html index.htm;
        }
    }
}

http {
    include       mime.types;
    include       /etc/nginx/conf.d/*.conf;
    include       /etc/nginx/sites-enabled/*;
}

# 错误：user 只能出现在 main 上下文
http {
    user nginx;
}

# 正确：把全局指令放回 main
user nginx;
http {
    server { ... }
}

http {
    index  index.html;          # http 级数组指令，子块仍可追加 index.php
}

http {
    root  /var/www/http;        # ① http 级 root
    server {
        # 未定义 root，继承 http 级的 /var/www/http
        location /api/ {
            root  /var/www/api; # ② location 覆盖为 /var/www/api
        }
    }
}

events {
    worker_connections  1024;   # 每 worker 最大并发连接数
    use                 epoll;  # Linux 默认 epoll，可省略
    multi_accept        on;     # 一次 accept 多个连接
    accept_mutex        on;     # 避免惊群
}

worker_processes  auto;     # 通常等于 CPU 核数
worker_rlimit_nofile  65535; # 提升单进程文件描述符上限

server {
    listen       80;
    server_name  example.com  www.example.com;
    root         /srv/www/example;
}

listen 80;                    # 所有 IPv4 的 80 端口
listen 443 ssl;               # TLS 端口
listen [::]:80;               # IPv6
listen 8080 default_server;   # 指定默认虚拟主机

server_name  example.com;            # 精确匹配优先
server_name  ~^www\.example\.com$;   # 正则需以 ~ 开头

location = /exact    { ... }  # 精确匹配，优先级最高
location ^~ /static/ { ... }  # 前缀匹配，命中后不再查正则
location ~  \.php$   { ... }  # 区分大小写的正则
location ~* \.(jpg|png)$ { ... } # 不区分大小写的正则
location /           { ... }  # 普通前缀，兜底

server {
    location /images/ { ... }                 # 普通前缀
    location = /images/logo.png { ... }       # 精确，优先级最高
    location ~* \.png$ { ... }                # 正则会覆盖更长前缀
}

location / {
    try_files $uri $uri/ @fallback;
}
location @fallback {
    proxy_pass http://backend;
}

# 典型坑：if 内使用 return/rewrite 以外的指令会出问题
location / {
    if ($request_uri ~* "\.(php)$") {
        proxy_pass http://backend;   # 可能产生意外行为
    }
}

if ($request_method = POST) {
    return 405;                       # 允许：return
}
if ($host != "example.com") {
    return 301 http://example.com$request_uri;  # 允许：rewrite/return
}

map $http_user_agent $is_mobile {
    default           0;
    "~*iPhone|Android"  1;
}
server {
    location / {
        if ($is_mobile) {
            return 302 /m/;           # 基于 map 结果安全分流
        }
    }
}

nginx -t              # 校验配置语法与上下文合法性
nginx -s reload       # 平滑重载，不中断已有连接
nginx -s reopen       # 重新打开日志文件
nginx -T              # 打印合并后的完整配置

# conf.d/gzip.conf —— 通用片段按需 include
gzip on;
gzip_types text/css application/json application/javascript;
gzip_min_length 1024;

# 启用虚拟主机：sites-available → sites-enabled 软链接
ln -s /etc/nginx/sites-available/example.com.conf /etc/nginx/sites-enabled/
nginx -t && nginx -s reload

# root 与 alias 的区别：root 拼接 URI，alias 直接替换
location /static/ { root /var/www; }       # 实际路径 /var/www/static/...
location /static/ { alias /srv/assets/; }  # 实际路径 /srv/assets/...