新增路由不生效主因是缓存未刷新或未加载：APP_DEBUG=true时缓存被跳过，需确保config/app.php中'app_debug'=>false；执行php think route:cache前须清空runtime/route/、显式加--annotation扫描注解、将动态路由提至app/route.php顶层执行，并验证route.php内容非空且配置route_cache=>true。
新增路由不生效，大概率不是你写错了，而是缓存没刷新、没生成，或者根本没加载上——ThinkPHP 的路由缓存机制在 APP_DEBUG=false 时会完全跳过源码解析，只读 runtime/route.php 里的静态数组。一旦这个文件没更新、路径不对、内容为空或被旧逻辑污染，新写的 Route::get()、@Route 注解、甚至 Route::domain() 子域名规则，全都会被无视。
APP_DEBUG=true 时缓存形同虚设
哪怕你刚跑完 php think route:cache，只要最终运行时 \think\App::debug() 返回 true（即 APP_DEBUG=true），框架就会强制重新解析全部路由定义，runtime/route.php 文件存在也白搭。这不是“缓存没生效”，而是“压根没走缓存”。
- 检查方式：在任意控制器里加
dump(\think\App::debug());，输出true就说明调试模式开着 - .env 中设
APP_DEBUG=false不保险，最终以config/app.php里的'app_debug' => false为准 - CI/CD 构建后若未显式关闭调试模式，上线即失效
注解路由没加 --annotation 参数
用 @Route 注解写的路由，在执行 php think route:cache 时不加 --annotation，就等于没扫描控制器——缓存文件里不会包含任何注解路由，新增的接口地址直接 404。
-
php think route:cache默认只处理route/app.php等 PHP 路由文件，不扫描类和方法 - 必须显式加参数：
php think route:cache --annotation - 注解只识别
app/controller/下的类，命名空间错位、文件名大小写不符（Linux 下敏感）、用了use别名引入，都会导致漏扫 - PHP 8 Attributes（如
#[Route]）在 TP 6.0.x 和 8.0 中不支持缓存，必须降级为 PHPDoc 注解
动态路由代码没在缓存生成前执行
Route::rule() 或数据库读取的动态路由，如果写在控制器方法、事件监听器、或闭包里，route:cache 命令运行时根本不会执行它——缓存只序列化静态结构，不跑运行时逻辑。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
立即学习“PHP免费学习笔记（深入）”；
- 正确做法：把动态路由注册逻辑提到
app/route.php文件顶层，确保命令执行时能立即执行并返回完整路由数组 - 或改用
Route::import('path/to/dynamic_routes.php')，该 PHP 文件可含简单逻辑（如读 JSON），但禁止 DB 查询、HTTP 请求等阻塞操作 - 验证是否进缓存：跑
php think route:list，输出里没你的动态路由，说明缓存阶段就没注册进去 - 升级到 TP 6.1+ 后，路由注册时机变晚，还必须确认
app/route.php是否被Route::rules()加载路径覆盖，否则也不生效
缓存文件残留或权限异常
删了 runtime/route.php 不代表清干净了。IDE 可能留下 .route.php.swp，Swoole 进程可能把旧缓存常驻内存，Docker 容器里 runtime 目录 UID 不一致会导致文件静默生成失败。
- 推荐清理方式：
php think clear:route，它比手动删更彻底，会同步清理关联临时索引 - 多应用模式下，每个应用子目录（如
app/admin/runtime/cache/route.php）都要单独清理 - Swoole/Hyperf 场景下，仅删文件不够，必须
php think swoole restart或发SIGUSR2信号 reload 进程 - 检查
is_file(RUNTIME_PATH . 'route.php')返回true，且文件内容不是空数组return [];—— 否则说明缓存生成阶段就中断了（比如某路由文件末尾多写了return）
最易被忽略的一点：缓存文件是否存在，和它是否被实际加载是两回事。即使 runtime/route.php 写入成功，若 config/route.php 里 'route_cache' => false，或 'route_config_file' 被设为空，框架照样绕过缓存走全量解析。
