How to Use fastcgi_cache in Nginx for Faster Web Performance

To use fastcgi_cache in Nginx, define a cache zone with fastcgi_cache_path, enable caching in your server block with fastcgi_cache, and set cache keys and rules. This caches responses from FastCGI servers, reducing load and speeding up responses.

Syntax

The fastcgi_cache directive enables caching of FastCGI responses. You first define a cache zone using fastcgi_cache_path which sets the cache location and size. Then, inside a server or location block, you use fastcgi_cache to activate caching and fastcgi_cache_key to specify how cache entries are identified.

• fastcgi_cache_path /path/to/cache levels=1:2 keys_zone=name:size inactive=time; defines cache storage.
• fastcgi_cache name; enables caching using the named zone.
• fastcgi_cache_key $scheme$request_method$host$request_uri; sets the cache key.

nginx

fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=FASTCGI_CACHE:10m inactive=60m;

server {
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_cache FASTCGI_CACHE;
        fastcgi_cache_key $scheme$request_method$host$request_uri;
        fastcgi_cache_valid 200 302 10m;
        fastcgi_cache_valid 404 1m;
        include fastcgi_params;
    }
}

Example

This example shows a simple Nginx configuration that caches PHP FastCGI responses for 10 minutes for successful requests and 1 minute for 404 errors. It uses a cache zone named FASTCGI_CACHE stored in /var/cache/nginx/fastcgi_cache.

nginx

fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=FASTCGI_CACHE:10m inactive=60m;

server {
    listen 80;
    server_name example.com;

    root /var/www/html;

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;

        fastcgi_cache FASTCGI_CACHE;
        fastcgi_cache_key $scheme$request_method$host$request_uri;
        fastcgi_cache_valid 200 302 10m;
        fastcgi_cache_valid 404 1m;

        fastcgi_cache_use_stale error timeout invalid_header http_500;
    }
}

Output

Nginx starts and caches FastCGI responses in /var/cache/nginx/fastcgi_cache, serving cached content for repeated requests within 10 minutes.

Common Pitfalls

Common mistakes when using fastcgi_cache include:

• Not setting fastcgi_cache_path before using fastcgi_cache.
• Using an incorrect or missing fastcgi_cache_key, causing cache misses.
• Not setting fastcgi_cache_valid to define how long responses are cached.
• Failing to set proper permissions on the cache directory.
• Not handling stale cache with fastcgi_cache_use_stale, which can improve availability.

Example of a wrong and right way:

nginx

# Wrong: Missing fastcgi_cache_path
server {
    location ~ \.php$ {
        fastcgi_cache FASTCGI_CACHE;
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }
}

# Right: Define cache path first
fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=FASTCGI_CACHE:10m inactive=60m;

server {
    location ~ \.php$ {
        fastcgi_cache FASTCGI_CACHE;
        fastcgi_cache_key $scheme$request_method$host$request_uri;
        fastcgi_cache_valid 200 10m;
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }
}

Quick Reference

Remember these key points when using fastcgi_cache:

• fastcgi_cache_path: Define cache location and size.
• fastcgi_cache: Enable caching in location/server block.
• fastcgi_cache_key: Unique key for cache entries.
• fastcgi_cache_valid: Set cache duration per response code.
• fastcgi_cache_use_stale: Serve stale cache on errors.

Key Takeaways

Always define a cache zone with fastcgi_cache_path before enabling fastcgi_cache.

Use fastcgi_cache_key to uniquely identify cached responses for better cache hits.

Set fastcgi_cache_valid to control how long different responses stay cached.

Use fastcgi_cache_use_stale to improve availability during backend errors.

Ensure proper permissions on the cache directory to avoid caching failures.