CachePathDependency仅被动检查文件mtime是否变化，不主动监听；缓存是否失效取决于isValid()返回false，常见问题包括路径错误、文件未保存、权限不足或未命中缓存读取。
CachePathDependency 不会自动更新缓存
它只是「检查文件路径是否变动」的被动依赖，不是监听器。缓存是否刷新，完全取决于你调用 Yii::$app->cache->get() 时，CachePathDependency 的 isValid() 是否返回 false —— 也就是对应文件的 filemtime() 发生了变化。
常见错误现象：CachePathDependency 配置好了，但改了模板或配置文件，缓存却没失效。
- 没触发缓存读取（比如用了
getOrSet()但回调没执行，或缓存 key 根本没命中） - 依赖的文件路径写错，
file_exists()返回false，此时依赖直接判定为无效（isValid() === false），导致缓存永不命中 - 文件被编辑但没保存（如 IDE 临时预览），或保存后系统缓存了
stat结果（极少见，但某些 NFS 或容器挂载场景会发生）
正确配置 CachePathDependency 的关键参数
必须显式传入 fileName 或 fileList，否则依赖不生效；同时注意路径是相对于 Yii::getAlias('@app') 还是绝对路径。
使用场景：缓存视图片段、生成的 PHP 配置、前端构建产物（如 dist/manifest.json）的解析结果。
示例：
$dependency = new \yii\caching\CachePathDependency([
'fileName' => '@app/config/params-local.php',
]);
-
fileName接受别名（如@app、@runtime），内部会自动调用Yii::getAlias() -
fileList可传数组，支持多个文件，任一变更都会使依赖失效 - 不要用
dirname(__FILE__)拼路径，容易在高级加载（如 phar、composer classmap）下出错 - 如果文件可能不存在，加个
skipOnMissingFile => false（默认true）来强制报错，方便定位路径问题
为什么改了文件缓存还不失效？检查这三点
这是最常卡住人的地方。不是框架有问题，而是路径、时机或缓存策略没对上。
- 确认缓存组件本身启用了（
Yii::$app->cache不是null，且驱动如FileCache或RedisCache正常工作） - 用
var_dump($dependency->isValid(Yii::$app->cache))直接测试依赖状态，比猜更准 - 检查文件权限：Web 进程用户（如
www-data）是否有权stat()该文件？尤其在 Docker 或 SELinux 环境下容易被忽略 -
CachePathDependency不感知内容变化，只看mtime；Git checkout、rsync 覆盖等操作若未更新时间戳，也需手动 touch
和 FileDependency 的区别与选型建议
CachePathDependency 是 FileDependency 的轻量替代，二者底层都靠 filemtime()，但设计意图不同。
性能影响几乎一致，但兼容性有差异：
-
FileDependency支持watchForChanges => true（仅开发环境有效，靠轮询，不推荐生产） -
CachePathDependency更纯粹，不带额外逻辑，适合明确知道“只要这个文件变，缓存就废”的场景 - Yii 2.0.40+ 中
CachePathDependency是官方推荐写法，FileDependency已标记为 legacy - 如果你依赖的是一个动态生成的文件（如
runtime/cache/version.txt），优先用CachePathDependency，语义更清晰
路径拼错、权限不到位、误以为它能“主动监听”，这三处最容易反复踩坑。其他都好调。
