Why include Splitting Is Mandatory
The main config should only carry the global skeleton: worker counts, the event model, log formats, and includes pointing at functional fragments. Writing sites directly into the main file makes every change a full-file diff, drives review cost up linearly, and makes rollback granularity unusable.
Split by responsibility, not by line count: one file for common HTTP settings, one for upstream pools, one per server block, and within each server, further splits per concern (rate limiting, static asset caching, real IP). Adding a site then means adding a file plus one include line.
Note that include paths resolve against `prefix` (usually `/etc/nginx`), not the directory of the current file — the most common stumbling block. Standardize on absolute paths across the repo and document the layout in a README.
# /etc/nginx/nginx.conf 主配置只留骨架
user nginx;
worker_processes auto;
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
log_format main "$remote_addr - $request_uri $status $body_bytes_sent $request_time";
access_log /var/log/nginx/access.log main;
sendfile on;
keepalive_timeout 65;
# map 必须定义在 http 层级，才能被 server/location 引用
include /etc/nginx/conf.d/maps/*.conf;
include /etc/nginx/conf.d/upstreams/*.conf;
include /etc/nginx/conf.d/servers/*.conf;
}Location Matching Priority Belongs in the Docs
Location matching order is the hardest part to reason about: exact `=` matches first, then the longest prefix match (within that prefix, regexes apply in declaration order unless `^~` short-circuits them), and finally regex-then-prefix fallbacks. This ordering must be frozen into a table in the docs.
The classic mistake is mixing `^~` and regex in the same scope. `^~` on a static asset directory is correct because it prevents regexes from interfering, but if a regex like `location ~ \.php$` sits at the same level, hit order becomes unpredictable. The safe rule: `^~` for static assets, regex only for dynamic requests.
Turn the priority into executable assertions. Probe each path class with `curl -I` and assert the response headers, then use `nginx -T` to dump the fully expanded configuration and confirm every include took effect with no duplicate definitions.
# 静态资源：^~ 终止正则匹配，避免被 location ~ .* 抢走
location ^~ /static/ {
root /var/www/app;
expires 30d;
add_header Cache-Control "public, immutable";
access_log off;
}
# 精确匹配：优先级最高
location = /healthz {
default_type application/json;
return 200 "{\"status\":\"ok\"}";
}
# 正则匹配：只处理动态请求
location ~ \.php$ {
fastcgi_pass unix:/run/php-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
# 兜底反代：只有上面都没命中才会到这里
location / {
proxy_pass http://app_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;
}map and geo: Turning Repetitive if Blocks into Declarative Rules
`map` defines an input-to-output lookup table at the http level. It typically turns a User-Agent into a rate-limit key, normalizes a domain to an upstream name, or maps legacy parameter names to new ones. It replaces long chains of `if ($http_user_agent ~ ...)`, and because it supports a `default` value it never falls through silently.
`geo` handles IP geolocation: `geo $variable { default 0; 1.0.0.0/8 1; ... }`, after which `if ($is_cn)` works inside a server block. Both directives support `include`, so CIDR lists and UA rules live in their own files and can even be generated from a GeoIP database.
Caveats: the first argument of `map` may be a variable, a string or a regex, but historically it cannot be a complex expression relying on captures (limitations around things like `$http_x_forwarded_for`). Keep large CIDR lists in a separate file so the main config stays readable.
# conf.d/maps/limit-key.conf —— http 层级
map $http_user_agent $limit_key {
default "other";
"~*bot|crawler|spider" "crawler";
"~*mobile|android|iphone" "mobile";
"" "nobot";
}
map $host $upstream_name {
default "app_backend";
api.example.com "api_backend";
admin.example.com "admin_backend";
}
# conf.d/maps/geo.conf —— CIDR 列表放独立文件
geo $is_blocked_region {
default 0;
include /etc/nginx/geo/blocked.cidr;
}
server {
listen 80;
server_name example.com;
if ($is_blocked_region) {
return 403;
}
location /api/ {
limit_req zone=perip burst=20 nodelay;
proxy_pass http://$upstream_name;
}
}Validation and a Security Baseline
Every config change must pass `nginx -t` before a reload — never a direct restart. `-t` parses all includes and validates syntax and directive legality; paired with `-T` it dumps the expanded config so you can diff what actually takes effect. Remember `-t` is static only and does not verify upstream reachability.
Two baseline items are most often missed: hiding the version with `server_tokens off;` and setting `limit_req`/`limit_conn` plus `client_max_body_size` explicitly — the default 1MB upload cap tends to surface as a surprise the day a new feature ships. For TLS, enable HSTS and drop weak protocols (`ssl_protocols TLSv1.2 TLSv1.3`).
Finally wire validation into CI: keep a template (template + env vars → final config) in the repo, render it in CI, run `nginx -t`, and only then allow deployment. Environment differences can no longer drift into production, and a local nginx version mismatch with production stops being a hidden compatibility hazard.
http {
server_tokens off;
client_max_body_size 20m;
limit_req_zone $binary_remote_addr zone=perip:10m rate=20r/s;
limit_conn_zone $binary_remote_addr zone=connperip:10m;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
# CI 校验脚本片段
set -euo pipefail
envsubst < templates/nginx.conf.tpl > build/nginx.conf
nginx -t -c "$PWD/build/nginx.conf"
nginx -T -c "$PWD/build/nginx.conf" | grep -E "server_name|location" > build/nginx.effective.txt