Laravel 文件元数据缓存需结合 Cache::remember、中间件、预热命令、事件监听及 inode+mtime 校验五种策略：① 用语义化键缓存单次查询；② 中间件统一拦截元数据接口；③ 部署时预热 Redis；④ 监听文件变更主动失效；⑤ 用 inode+mtime 组合键实现零延迟校验。
当 Laravel 应用频繁读取文件大小、修改时间、MIME 类型或哈希值时，每次调用 filesize()、filemtime() 或 mime_content_type() 都会触发真实磁盘 I/O，导致接口响应变慢、CPU 负载升高，尤其在高并发下载页、附件管理后台或静态资源校验场景下尤为明显。
用 Cache::remember 缓存单次元数据查询
这一步操作起来很简单，直接封装原生函数即可，适用于静态资源路径固定、变更极少但被高频访问的场景，比如 CDN 资源版本校验或后台附件列表。
第一步：为文件路径生成语义化缓存键，例如 file:meta:/storage/app/invoices/2026-07-report.pdf，避免使用裸路径拼接，防止特殊字符引发键冲突。
第二步：在业务逻辑中调用 Cache::remember()，传入键名、TTL（秒）和闭包；闭包内执行原生函数获取元数据，返回关联数组。
第三步：设置合理过期时间——对 PDF 报告类文件设 3600 秒足够，但若业务要求“文件一改立刻生效”，则必须配合事件监听器主动清除缓存，否则将返回脏数据。
示例代码：Cache::remember('file:meta:/storage/app/logo.svg', 7200, fn() => ['size' => filesize(storage_path('app/logo.svg')), 'mtime' => filemtime(storage_path('app/logo.svg')), 'mime' => mime_content_type(storage_path('app/logo.svg'))])
构建元数据缓存中间件
当你有多个 API 接口统一返回文件详情（如 /api/file/{id}/meta、/v1/asset/{hash}/info），又不想在每个控制器里重复写缓存逻辑时，中间件是最干净的解法。
方法一：手动实现基础缓存拦截
执行 php artisan make:middleware CacheFileMetadata 创建中间件；
在 handle() 中解析请求参数（如 $request->route('id')），查出对应存储路径；
生成缓存键（建议含 disk 名称，如 file:meta:local:/uploads/abc.jpg），优先从缓存读取；
命中则构造 JSON 响应并返回，未命中则调用 Storage::disk('local')->getMetadata($path) 获取数据并写入缓存；
【中间件内必须显式指定 Redis 驱动，否则开发环境 file 驱动可能因文件锁导致并发请求阻塞】
方法二：复用 Laravel 自带缓存中间件（仅限简单响应）
路由定义中直接附加 ->middleware('cache.headers:public;max_age=3600')，但它只缓存整个 HTTP 响应体，不感知文件内容变更，适合完全静态的元数据展示页。
预热元数据缓存并持久化至 Redis
适用于部署后一次性加载全部已知文件元数据，彻底消除运行时 I/O，常见于上传目录结构稳定、文件集可枚举的场景，例如每月归档的 PDF 报告库。
① 执行 php artisan make:command WarmupFileMetadataCache 创建命令类；
② 在 handle() 方法中，调用 Storage::disk('public')->files('reports/2026/') 获取目标目录下所有文件路径；
③ 对每个路径，同步执行 filesize()、filemtime() 和 Storage::mimeType()，组装为数组；
④ 使用 Cache::store('redis')->set($key, $data, 86400) 写入 Redis，TTL 设为 24 小时；
⑤ 将该命令加入部署脚本，确保每次上线后自动执行；
注意：不要在 Web 请求中调用此命令，它会阻塞主线程且耗时较长。
监听文件事件自动更新缓存
当文件可能被外部进程（如 FTP 上传、定时脚本、第三方服务回调）直接写入 storage 目录，而 Laravel 无感知时，仅靠 TTL 过期无法保证元数据实时性，必须引入事件驱动机制。
首先确认你的文件系统支持 inotify（Linux）或 kqueue（macOS），否则监听不可靠；
安装 spatie/laravel-event-sourcing 或自建 FileChanged 事件，触发时机为 Storage::put()、Storage::delete() 后；
监听器中根据事件携带的路径，计算对应缓存键（如 file:meta:local:/uploads/photo.jpg），执行 Cache::forget($key) 主动失效；
下次请求自然触发 Cache::remember() 重建，确保元数据始终最新；
这一步不能省略——否则缓存雪崩风险极高，尤其在用户上传后立即查看详情的流程中。
用 inode + mtime 组合键实现零延迟校验
当业务要求“绝对实时”但又无法承受每次读取都走磁盘时，可用文件系统底层属性做轻量级校验，跳过全量元数据重读。
原理：同一文件的 inode 编号与最后修改时间（mtime）组合具备强唯一性，只要二者未变，元数据必然未变；
第一步：首次读取时，缓存完整元数据，并额外存一份 inode:mtime 校验键，例如 file:check:/storage/app/data.json → [123456, 1722952340]；
第二步：后续请求先读该校验键，再用 stat() 获取当前 inode 和 mtime；
第三步：若两者完全一致，直接返回原缓存元数据；若任一不同，则刷新元数据并更新校验键；
这个方案把 I/O 从三次（size/mtime/mime）压到一次 stat() 系统调用，性能提升显著，且无需依赖外部事件。
