LaravelAPI缓存不生效怎么排查_Laravel缓存驱动与命令检查【指南】-Laravel-PHP中文网

最常见原因是缓存驱动配置错误或未生效；需检查 config/cache.php 默认驱动、.env 中 CACHE_DRIVER 值及是否被 config:cache 覆盖，Redis 还需验证连接与序列化兼容性。

laravelapi缓存不生效怎么排查_laravel缓存驱动与命令检查【指南】

缓存没走 Redis 或 File，`Cache::get()` 总返回 null

最常见原因是缓存驱动没配对，或者配置没生效。Laravel 默认用 array 驱动（内存级、请求间不共享），开发时看着像“失效”，其实是压根没存到持久介质里。

检查 config/cache.php 中 'default' 对应的驱动是否为 'redis' 或 'file'，不是 'array'
确认 .env 里 CACHE_DRIVER=redis（或对应驱动），且该值未被 config:cache 缓存覆盖 —— 运行 php artisan config:clear 再试
Redis 驱动下，还要核对 config/database.php 的 redis.default 是否连得通：用 php artisan tinker 执行 Redis::ping() 看是否报错
Cache::put('test', 'ok', 60) 后立刻 Cache::get('test') 返回 null？大概率是驱动没切过去，而不是缓存逻辑写错了

`Cache::remember()` 在 API 路由里不缓存响应

API 路由默认无 session，但某些缓存键生成逻辑（比如依赖 Request 的 query 或 header）若没显式控制，会导致每次请求 key 不同，看似“不缓存”。更隐蔽的是中间件顺序问题。

Cache::remember() 的 key 必须稳定 —— 避免直接用 $request->fullUrl()，改用 url()->current() . '?' . http_build_query($request->except('page')) 这类可控拼接
检查路由是否套了 throttle 或自定义中间件，它们可能在缓存读取前就终止了请求（比如未登录时 401 直接返回，根本没走到 remember 逻辑）
API 路由默认不启用 StartSession 中间件，但如果你在缓存 key 里误用了 session()->getId()，那每次都是新 key
用 Cache::getStore()->getDriverName() 在代码里打个日志，确认运行时实际用的确实是预期驱动，不是 fallback 到了 array

`php artisan cache:clear` 清不掉 API 缓存

这个命令只清 Laravel 自己的缓存池（config、route、view），不碰你手动用 Cache::put() 存的数据 —— 它们属于「应用缓存」，得用 php artisan cache:forget 或对应驱动命令清。

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

想清所有应用缓存：用 php artisan cache:clear --tags=*（仅限支持 tag 的驱动，如 redis、memcached）；file 驱动不支持 tags，得手动删 storage/framework/cache/data/ 下文件
Redis 用户可直连清理：redis-cli -n 0 FLUSHDB（注意 -n 指定 database，对应 database.php 中 redis 配置的 database 值）
别信 IDE 或终端里刚执行完 cache:clear 就马上 curl 测试 —— 某些代理、Nginx fastcgi_cache、甚至浏览器本身也缓存了 200 响应，先加 Cache-Control: no-cache 头排除干扰

API 缓存命中率低，`Cache::has()` 总是 false

表面是“没命中”，实际常因 TTL 设置过短、key 冲突、或序列化失败导致写入静默失败。尤其当缓存值含 Closure、resource 或未实现 Serializable 的对象时，Redis 驱动会跳过存储但不报错。

TTL 小于 1 秒会被 Laravel 截断为 0，变成“不缓存”，检查传给 Cache::put() 的秒数是不是计算出来的浮点数（比如 microtime(true) 差值）
避免用动态变量拼 key 时引入不可见字符：比如 $key = 'api_user_' . $request->ip() . '_' . $request->userAgent()，User-Agent 里可能有换行或控制符，建议 md5() 或 sha1() 哈希后再用
Redis 存不了 PHP resource（如 file handle）或匿名函数，Cache::put('x', fopen(...)) 看似成功，实则没写入 —— 开启 redis.log_level = 4 查日志，或临时加 try { Cache::put(...); } catch (\Exception $e) { \Log::error($e); }
File 驱动在高并发下可能因文件锁导致写失败，Cache::put() 返回 true 但文件实际为空，用 ls -la storage/framework/cache/data/ 看文件大小是否为 0

缓存链路长，从 key 生成、驱动连接、序列化、存储、再到读取反序列化，任何一环出哑巴错都难定位。最有效的排查动作不是翻文档，而是每一步加一行 Log::debug() 打出 key、driver name、TTL、以及 Cache::get() 的返回值类型 —— 很多时候你以为它“没生效”，其实只是 key 对不上。