Nginx的FastCGI缓存是提升PHP等动态站点性能的重要手段，而cache key是决定缓存是否命中的核心因素，很多场景下开发者配置了缓存规则却发现缓存没有按照预期生效，大多和cache key的配置有关。
FastCGI Cache Key基础配置逻辑
FastCGI Cache Key的作用是为每个请求生成一个唯一的标识，Nginx会根据这个标识来判断当前请求是否有对应的缓存内容。基础配置需要先在http块定义缓存路径和key的格式，再在server或location块中启用缓存并关联对应的key规则。
基础的配置结构如下：
http {
# 定义FastCGI缓存路径，levels是目录层级，keys_zone是缓存名称和内存大小，max_size是磁盘最大缓存大小
fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=php_cache:10m max_size=1g inactive=60m;
# 定义默认的缓存key格式，使用请求方法、host、请求uri拼接生成唯一key
fastcgi_cache_key "$request_method$host$request_uri";
server {
listen 80;
server_name example.ipipp.com;
location ~ .php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi.conf;
# 启用上面定义的php_cache缓存
fastcgi_cache php_cache;
# 缓存有效期设置
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404 1m;
}
}
}
Cache Key不生效的常见原因
1. 变量使用错误或未正确获取变量值
很多开发者会自定义缓存key，比如加入查询参数、用户标识等变量，但如果变量不存在或者拼写错误，会导致key生成异常。比如想要根据请求的查询参数id生成key，却写成了$arg_Id（Nginx变量区分大小写），或者变量对应的请求头没有传递，就会导致key不符合预期。
2. 配置作用域错误
fastcgi_cache_key的配置作用域是http、server、location，如果在http块定义了全局的key，又在location块重新定义了key，但是location块的配置没有生效（比如正则匹配优先级问题），就会导致实际使用的key和预期不一致。另外如果fastcgi_cache_key放在fastcgi_cache指令之后，也可能导致配置不生效。
3. 缓存规则冲突覆盖
如果配置了fastcgi_cache_bypass（绕过缓存的条件）或者fastcgi_no_cache（不缓存的条件），当请求满足这些条件时，即使key生成正确，也不会触发缓存匹配或者缓存存储，看起来像是key不生效。比如配置了fastcgi_cache_bypass $http_pragma，当请求头包含Pragma时就会绕过缓存，导致缓存无法命中。
4. 缓存已过期或被清理
如果缓存的inactive时间设置过短，或者磁盘缓存达到了max_size被清理，即使key匹配正确，也找不到对应的缓存内容，容易被误认为key不生效。可以通过查看Nginx的缓存目录文件，或者开启缓存日志来确认是否是缓存过期导致的问题。
正确的配置方案与验证方法
完整正确配置示例
以下是一个包含查询参数、支持按请求方法区分的缓存key配置示例，适合大多数动态站点场景：
http {
# 缓存路径配置，inactive表示60分钟没有被访问的缓存会被清理
fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=php_cache:10m max_size=1g inactive=60m;
server {
listen 80;
server_name example.ipipp.com;
# 定义缓存日志格式，方便排查问题
log_format cache_log '$remote_addr - $request - $upstream_cache_status';
location ~ .php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi.conf;
# 启用缓存
fastcgi_cache php_cache;
# 正确的cache key配置，包含请求方法、host、uri、查询参数，排除无用的查询参数
fastcgi_cache_key "$request_method$host$request_uri$is_args$args";
# 缓存有效期配置
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404 1m;
# 设置缓存日志
access_log /var/log/nginx/cache_access.log cache_log;
# 可选：设置绕过缓存的条件，比如POST请求不缓存
fastcgi_cache_bypass $request_method POST;
fastcgi_no_cache $request_method POST;
}
}
}
配置验证方法
配置完成后可以通过以下步骤验证key是否生效：
- 重启Nginx使配置生效，执行
nginx -s reload - 发送两次相同的请求，查看缓存日志中的
$upstream_cache_status字段，第一次应该是MISS，第二次是HIT，说明缓存命中正常 - 修改请求的查询参数或者请求方法，再次请求，查看日志是否为MISS，说明key随参数变化正确生成
- 可以查看缓存目录下的文件，通过md5计算key的哈希值，对应缓存文件的目录层级，确认key生成逻辑正确
如果遇到key还是不生效的情况，可以开启Nginx的debug日志，查看请求处理过程中变量的取值和缓存匹配的具体过程，快速定位问题所在。
NginxFastCGI_Cachecache_key缓存配置修改时间：2026-07-01 13:39:31