Unlock Faster Web Performance: Mastering Nginx Caching Techniques

Nginx Caching Explained

Nginx is a powerful web server and reverse proxy that can cache static content. Caching can be client‑side (browser) or server‑side (proxy or CDN).

Client‑Side Cache

Browser cache stores resources locally, reducing network traffic and speeding up requests. It can be strong (no HTTP request) or negotiated (requires validation with the server).

Strong Cache (no request)

Resources are read directly from local storage; the HTTP status is 200 (from memory or disk cache). Relevant headers: Cache‑Control, Expires.

Cache‑Control Expires

Negotiated Cache (requires request)

If the cached resource is expired, the browser sends If‑Modified‑Since or If‑None‑Match. The server returns 304 Not Modified to use the local copy, or a new response if the content changed.

Cache‑Control header: set max‑age to define freshness, e.g. Cache-Control: max-age=3600 Expires header: specify an absolute expiration date, e.g. Expires: Tue, 01 Jan 2025 00:00:00 GMT Last‑Modified / If‑Modified‑Since: server sends Last‑Modified; client sends If‑Modified‑Since; server returns 304 if unchanged.

ETag / If‑None‑Match: server provides ETag; client sends If‑None‑Match; server returns 304 if unchanged.

Cache validation flow diagram:

Force cache works by checking Expires and Cache‑Control; if not expired, the browser uses the cached file.

Server‑Side Cache

Proxy cache is implemented by Nginx. Cached responses are stored on disk and served directly on subsequent requests, reducing load on the upstream server.

Enable Nginx Cache

Reverse Proxy Configuration

Define proxy_cache_path with parameters such as levels, inactive time, keys_zone, and max_size.

proxy_cache_path /tmp/nginx/cache levels=1:2 inactive=60s keys_zone=mycache:10m max_size=10g;

Reference the cache in http, server or location blocks:

user nginx;
events {}
http {
    proxy_cache_path /tmp/nginx/cache levels=1:2 inactive=60s keys_zone=mycache:10m max_size=10g;
    server {
        listen 80;
        location /cache {
            proxy_pass http://192.168.1.135:8080;
            proxy_cache mycache;
            add_header cache $upstream_cache_status;
        }
    }
}

Upstream server must send cache directives (e.g., X-Accel-Expires, Expires, or Cache‑Control "max-age=") so that Nginx knows how long to keep the object.

server {
    listen 8080;
    location /cache {
        add_header X-Accel-Expires 100; # notify proxy cache 100s
        alias /www/html/docs/;
    }
}

Cache status values ($upstream_cache_status): MISS, HIT, EXPIRED, UPDATING, STALE, BYPASS, REVALIDATED.

Example of cache verification with curl showing MISS then HIT:

❯ curl http://192.168.1.134/cache/ -I
HTTP/1.1 200 OK
... 
cache: MISS

❯ curl http://192.168.1.134/cache/ -I
HTTP/1.1 200 OK
... 
cache: HIT

Cache Control Directives

Key directives include: proxy_cache_bypass – conditions that skip cache. proxy_no_cache – conditions that prevent caching. proxy_cache_key – defines the cache key. proxy_cache_methods – HTTP methods that can be cached. proxy_ignore_headers – headers that cause Nginx to ignore upstream caching rules. proxy_cache_valid – sets expiration times for specific response codes. proxy_cache_min_uses – number of requests before an object is cached. proxy_buffering, proxy_buffers, proxy_buffer_size – control buffering of upstream responses. proxy_temp_path, proxy_max_temp_file_size, proxy_temp_file_write_size – manage temporary files. proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout – set timeouts. proxy_cache_lock, proxy_cache_lock_timeout, proxy_cache_lock_age – lock handling for concurrent cache updates. proxy_cache_use_stale – serve stale content on errors. proxy_cache_revalidate – add conditional headers when cached content expires.

These directives allow fine‑grained control over caching behavior, performance, and reliability.