Nginx HTTP cache policy

Use case 1: Long-term cache for static assets

# Configure long-term caching for static assets
# - For filenames with a content hash (e.g., main.a1b2c3d4.js), a 1-year cache with 'immutable' is recommended.
location ~* "\.[a-f0-9]{8,}\.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$" {
    # For assets with a hash generated by build tools: cache for 1 year, and instruct the browser to never revalidate.
    add_header Cache-Control "public, max-age=31536003, immutable" always;
    access_log off;
}

# - For filenames that are fixed and rarely change (e.g., logo.png), use a 30-day cache.
location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$ {
    # For generic static assets without a hash: cache for 30 days and allow both CDN and browser caching.
    add_header Cache-Control "public, max-age=2592000" always;
    access_log off;
}

Use case 2: Cache for HTML and SPA

HTML pages, especially the entry file for a single-page application (SPA) like index.html, are updated frequently with each new deployment. Therefore, avoid long-term caching for them. For performance, you can allow browsers to cache these files but should require them to revalidate with the server before each use.

# For directly requested HTML files
location ~* \.html$ {
    # Allows browser caching but requires revalidation with the server before each use.
    # The 'private' directive prevents an intermediate proxy (like a CDN) from caching this response.
    # The server must provide an ETag or Last-Modified header to support validation.
    add_header Cache-Control "private, no-cache, must-revalidate" always;
}

Use case 3: No cache for dynamic and sensitive content

For dynamically generated or sensitive content, such as an API endpoint, user profile page, or payment page, prevent browsers and intermediate proxies (like CDNs or shared caches) from storing the response. This prevents data leaks and inconsistencies.

# Example: For dynamic PHP scripts (adjust the path based on your setup)
location ~ \.php$ {
    # ... other PHP-FPM configurations ...

    # Disable all caching: Browsers, proxies, and CDNs must not store the response.
    # 'no-store' is the strictest cache control directive.
    add_header Cache-Control "no-store" always;
}

Changes not taking effect

Cause:

1. The sudo nginx -s reload command was not executed.

2. A browser, CDN, or proxy server is serving a stale response.

3. Incorrect location block matching priority.

Solution:

1. Use curl -I http://your-url to verify the response header directly from the server.

2. Check the location block order. Regular expression matches (like ~* \.(css|js)$) take precedence over prefix matches (like /static/). A request might be handled by the wrong rule because of this priority.

Dynamic content incorrectly cached

Cause: The regular expression for static assets is too broad (for example, ~* \.js$ matches /api/user.js).

Solution:

1. Restrict the path: location ~* ^/static/.*\.(css|js)$

2. Ensure the location for dynamic interfaces such as /api/ and \.php$ is matched with priority or explicitly excluded from caching.

Conflicting cache policies

• Cause: Multiple location blocks match the same request, but only the first one takes effect.

• Solution: Use a map block to consolidate policies and dynamically set the cache policy based on the content type.

  # In the http block
  map $sent_http_content_type $cache_control {
      ~^image/    "public, max-age=2592000";
      text/css    "public, max-age=2592000";
      application/javascript "public, max-age=2592000";
      default     "no-cache";
  }
  
  # In the server block
  add_header Cache-Control $cache_control always;