ThinkPHP缓存失效主因是APP_DEBUG=true强制跳过缓存或runtime目录权限异常；需先确认debug关闭、配置生效顺序及目录可写性，再排查模板路径动态化、注解路由PSR-4规范与扩展缺失等问题。
ThinkPHP开发环境缓存经常失效，不是代码写错了，而是APP_DEBUG=true强制跳过所有缓存加载逻辑，或runtime目录权限异常导致缓存文件写入失败、被静默忽略——哪怕你刚执行过php think route:cache，只要debug开关开着，缓存就形同虚设。
确认APP_DEBUG是否真正关闭
第一步：在任意控制器方法中插入两行调试代码并访问接口：
dump(\think\App::debug());
dump(is_file(RUNTIME_PATH . 'route.php'));
第一行输出【true】表示APP_DEBUG仍为true，此时框架完全不读取route.php，哪怕它存在也毫无作用；第二行输出false说明缓存文件根本没生成，问题出在写入环节而非读取环节。
第二步：检查配置生效顺序——.env里设APP_DEBUG=false没用，必须确认config/app.php中最终解析结果是'app_debug' => false。TP8.0会合并多层配置，.env可能被config/app.php里的硬编码覆盖。
立即学习“PHP免费学习笔记（深入）”；
检查runtime目录可写性与路径合法性
执行ls -ld runtime/，确认Web服务器用户（如www-data）对该目录有写权限。若权限不足，php think route:cache命令会静默失败，不报错也不生成文件。
注意：Docker环境中常见陷阱是runtime挂载为volume后，容器内用户UID与宿主机不一致，导致chown失效；此时需在Dockerfile中显式指定USER www-data，或启动时加--user参数。
若项目启用了自定义template_cache_path，运行var_dump(config('template.template_cache_path'))验证实际路径。含../或非法字符的路径会被静默忽略，退回到默认runtime/cache/，而你清理的可能是另一个目录。
模板缓存失效的典型诱因
方法一：关掉模板缓存
在config/template.php中设'template' => ['cache' => false]。开发阶段这是最稳妥的做法，改完模板立刻生效，不用反复清理runtime/view/。
方法二：强制时间戳校验
保持缓存开启但设'template.cache_expire' => 0，并确保源模板文件修改时间确实更新。Linux ext4文件系统时间精度为1秒，快速连续保存可能被判定未变更，可用touch命令手动刷新：touch template/index.html。
方法三：避开动态路径陷阱
错误写法：$this->fetch($module . '/index')→ 模板路径含变量，框架跳过缓存编译；正确写法：使用固定字符串标识，或通过配置映射表转为字面量，例如$config['tpl_map'][$module] ?? 'index'。
注解路由缓存不生效的硬性条件
① 控制器类必须严格符合PSR-4规范：app\controller\User对应app/controller/User.php，大小写错一个字母、命名空间少一个反斜杠，@Route注解就会被完全忽略；
② 注解只能写在控制器类或public方法上，trait、父类、static方法里的@Route不会被采集；
③ 执行php think route:cache --annotation时，必须确保vendor/autoload.php已加载且think\Container可实例化——缺少mbstring扩展会导致AnnotationReader初始化失败，但错误被静默吞掉，route.php生成为空数组。
