缓存读取失败首要排查路径真实性与权限：需用realpath()或__DIR__拼接路径，双重验证is_dir()和is_writable()，确认Web与CLI用户权限一致，并开启错误报告或使用error_get_last()捕获具体原因。
缓存文件路径是否真实存在且可读
PHP文件缓存（如 file_get_contents() 读取缓存、或自定义缓存逻辑）失败，第一反应不是代码逻辑错，而是路径根本没生成或权限不对。常见现象是返回 false 或空字符串，file_exists() 返回 false，但你以为“刚写进去的缓存肯定在”。
- 检查缓存路径是否用
realpath()或__DIR__拼接，避免相对路径在 CLI 和 Web 环境下行为不一致 - 确认缓存目录存在：用
is_dir($cacheDir)+is_writable($cacheDir)双重验证，不能只靠mkdir()的返回值（它可能静默失败） - Web 服务器用户（如
www-data或nginx）必须对缓存文件有读权限；CLI 脚本运行时用户（如ubuntu）可能不同，导致“手动cat能看到，PHP 读不到” - 若路径含变量（如时间戳、ID），打印出完整路径再
ls -l手动核对，别信日志里截断的路径
file_get_contents() 失败但没报错的原因
默认情况下 file_get_contents() 遇到权限/路径问题会触发 E_WARNING，但若错误报告被关闭（error_reporting(0) 或 ini_set('display_errors', '0')），就只剩一个 false 返回值，毫无提示。
- 临时开启错误显示：
error_reporting(E_ALL); ini_set('display_errors', '1');，或查 PHP 错误日志（error_log配置项指向的文件） - 不要直接用
file_get_contents($file)，改用带错误上下文的写法：$content = @file_get_contents($file); if ($content === false) { $err = error_get_last(); error_log("Cache read failed: {$file}, " . ($err['message'] ?? 'unknown error')); } - 注意
allow_url_fopen=Off不影响本地文件读取，但若路径误写成http://或phar://协议，就会因该配置失败
缓存文件被意外覆盖或清空
看似“读取失败”，实则是缓存写入阶段就出了问题：文件创建了但内容为空，或写入中途被中断，或多个进程同时写入导致竞态。
- 检查写入逻辑是否用了
file_put_contents($file, $data, LOCK_EX)—— 缺少LOCK_EX在并发场景下极易写入空内容 - 避免先
unlink()再file_put_contents()：这中间存在时间窗口，读取方可能撞上“文件不存在”状态 - 写入后立刻用
filesize($file)校验长度，或用md5_file($file)对比原始数据哈希，确认写入完整性 - 注意 NFS 或某些容器卷挂载场景下，
flock()可能失效，此时需改用原子重命名（file_put_contents($tmp, $data); rename($tmp, $file)）
时区/时间判断导致缓存误判过期
很多文件缓存依赖 filemtime() 判断有效期，但 PHP 的时区设置（date_default_timezone_set()）不影响 filemtime() 返回的 Unix 时间戳，只影响 date() 输出——这点容易混淆。
立即学习“PHP免费学习笔记（深入）”；
- 过期判断别写成
time() - filemtime($file) > 3600后直接读，要先file_exists()和is_readable()，否则filemtime()本身就会触发警告 - 如果缓存文件由另一个系统（如 Python 脚本）生成，注意其写入时间是否受系统时钟漂移或 NTP 同步影响，导致 PHP 读到的时间戳异常偏大/小
- 调试时直接
var_dump(filemtime($file), time(), date('Y-m-d H:i:s'))，三者对照看是否时间差合理
缓存排错最耗时间的地方，往往不在“怎么读”，而在“谁写的、什么时候写的、写完还是不是它”。多打一行 var_dump(fileperms($file))，可能比翻三页文档更快定位问题。
