Mastering Nginx Caching: From Client‑Side Strategies to Advanced Proxy Cache Configuration

Nginx is a powerful web server and reverse proxy that can cache static content to improve performance. Caching can be divided into client‑side (browser) caching and server‑side (proxy) caching.

Client‑Side Caching

Browser caching is the fastest because resources are retrieved locally, reducing network traffic. It includes two modes:

Strong cache (no HTTP request): the browser uses the cached file directly until the Cache‑Control: max‑age or Expires header expires.

Negotiated cache (HTTP request): the browser sends If‑Modified‑Since or If‑None‑Match to the server; the server replies with 304 Not Modified if the cached copy is still valid.

Key response headers for strong cache are Cache‑Control and Expires. For negotiated cache, the server can use Last‑Modified / If‑Modified‑Since (HTTP/1.0) or ETag / If‑None‑Match (HTTP/1.1) to validate the cached copy.

Server‑Side (Proxy) Caching

When Nginx acts as a reverse proxy, it can store upstream responses on disk and serve them directly on subsequent requests, reducing load on the origin server. The core directives are: proxy_cache_path defines the cache directory, levels, size, inactive time, and shared memory zone. proxy_cache enables caching for a specific location using a previously defined zone. proxy_cache_valid sets expiration times for different HTTP status codes. proxy_cache_key customizes the cache key (default is $scheme$proxy_host$request_uri).

Typical configuration example:

proxy_cache_path /tmp/nginx/cache levels=1:2 keys_zone=mycache:10m max_size=10g inactive=60s;
server {
    listen 80;
    location /cache {
        proxy_pass http://192.168.1.135:8080;
        proxy_cache mycache;
        proxy_cache_valid 200 302 100s;
        proxy_cache_valid 404 200s;
        proxy_cache_bypass $arg_nocache $arg_comment;
        proxy_no_cache $cookie_nocache $arg_nocache $arg_comment;
        add_header cache $upstream_cache_status;
    }
}

Additional directives control which requests are cached ( proxy_cache_methods, proxy_cache_min_uses), how buffers are allocated ( proxy_buffering, proxy_buffers, proxy_buffer_size), and timeouts for upstream connections ( proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout).

Cache Validation and Stale Content

When a cached entry expires, proxy_cache_revalidate adds If‑Modified‑Since and If‑None‑Match to the upstream request. If the upstream returns 304, Nginx updates the cache and serves the fresh copy.

Historical (stale) cache can be used when the upstream is unavailable using proxy_cache_use_stale (e.g., proxy_cache_use_stale http_404;).

Bypassing and Controlling Cache

Use proxy_cache_bypass or proxy_no_cache with variables (e.g., query parameters nocache or comment) to force a request to skip the cache or prevent caching of a response.

Testing Cache Behavior

Example curl commands demonstrate cache MISS, HIT, BYPASS, STALE, and REVALIDATED states, and the $upstream_cache_status variable can be added to responses for debugging.

Overall, proper use of Nginx caching directives can dramatically reduce latency, lower origin server load, and improve scalability for web applications.