Serving and routing requests
Server blocks and server_name
Nginx picks a server block in two steps. First by the address and port the connection arrived on (listen). Then, among the servers listening there, by the Host header (or the SNI name for TLS) against server_name:
- An exact name:
server_name shop.example.com; - The longest wildcard starting with
*:*.example.com - The longest wildcard ending with
*:shop.* - The first matching regular expression, in file order:
~^(?<tenant>.+)\.example\.com$
If nothing matches, the default server for that port handles the request: the one marked listen 80 default_server;, or else the first one defined. Always define an explicit default that returns 444 (close the connection) or a plain 404, so requests for unknown names or raw IP addresses don't land on a real site by accident.
server {
listen 80 default_server;
server_name _;
return 444;
}
Location matching
Inside the chosen server, Nginx matches the request path (without the query string) against location blocks. The order of the file matters less than people expect:
| Modifier | Meaning | Priority |
|---|---|---|
= /path |
Exact match | Used immediately if it matches |
^~ /prefix |
Prefix; if it is the longest prefix, skip regex checks | Next |
~ regex / ~* regex |
Regular expression, case-sensitive / insensitive | First match in file order wins |
/prefix |
Plain prefix | Longest one is remembered; used only if no regex matches |
So the algorithm is: check exact matches; find the longest prefix; if that prefix has ^~, stop; otherwise try regexes in order and use the first match; if none match, use the remembered longest prefix.
location = /healthz { access_log off; return 200 "ok\n"; }
location ^~ /static/ { root /srv/app; expires 30d; }
location ~* \.(png|jpg)$ { root /srv/img; }
location /api/ { proxy_pass http://api; }
location / { try_files $uri /index.html; }
A request for /static/logo.png is served by ^~ /static/, not by the image regex, because ^~ stops the regex search. Without ^~ the regex would win.
Static files and try_files
root /srv/app;appends the full URI:/static/a.cssbecomes/srv/app/static/a.css.alias /srv/assets/;replaces the matched part:location /static/ { alias /srv/assets/; }serves/srv/assets/a.css. Mismatched trailing slashes onaliasare a well-known path traversal risk (/static../), so keep both with a slash.try_files $uri $uri/ /index.html;tries each path in turn and falls back to the last one. This is how single-page apps (React, Vue) get client-side routes to work.sendfile on; tcp_nopush on;let the kernel copy files straight to the socket.