thinkphp 8 注解路由需四步闭环：安装扩展、调用 annotationroute::init()、配置 controllers 命名空间、清缓存并加 --annotation 参数重建，缺一即静默失效。
注解路由在 ThinkPHP 8 中不是开箱即用的功能，漏掉初始化或配置任一环节，php think route:list 就完全看不到你的 #[Route]，请求直接 404 —— 不报错、不提示、不警告，纯静默失效。
扩展没装、AnnotationRoute::init() 没调，注解就等于没写
TP8 把注解路由能力抽成了独立扩展，框架本身不内置。常见错误是只写了 #[Get('user/:id')]，却忘了两件硬性前提：
- 执行
composer require topthink/think-annotation安装扩展（TP8.0+ 不再预装） - 在
app/bootstrap.php或自定义服务提供者中显式调用AnnotationRoute::init() -
config/annotation.php中的'route' => ['enable' => true]只控制解析器开关，不调init()，扫描根本不会启动
#[Get] 和 #[Route] 参数支持差异极大，别混用
#[Get] 是语法糖，仅等价于 #[Route(path, method: 'GET')]，其余字段全被忽略：
- 在
#[Get('admin/:id')]里加middleware: 'auth'—— 静默丢弃，不生效也不报错 - 需要中间件、域名约束（
domain）、变量正则（pattern）、路由名（name）等，必须用#[Route]显式声明 -
#[Route('admin/:id', method: 'GET', middleware: 'auth', domain: 'admin.example.com')]才是完整写法
多应用下控制器不被扫描？改 config/annotation.php 的 controllers 配置
默认只扫 app\controller 命名空间，app\admin\controller 或 app\api\controller 全部被跳过：
- 打开
config/annotation.php，修改'controllers'数组，补全路径（注意双反斜杠）：'controllers' => ['app\controller', 'app\admin\controller', 'app\api\controller'] - 路径写成
appcontroller（少反斜杠）会解析失败，IDE 可能不报错但运行时无效 - 改完必须执行
php think clear:route清缓存，否则旧扫描结果仍残留
路由缓存和 APP_DEBUG 冲突，调试时容易误判
开发中常因缓存未清或 APP_DEBUG=true 导致路由“看似不生效”：
-
APP_DEBUG=true时，框架强制跳过所有路由缓存，每次请求都重新解析 —— 此时php think route:cache生成的文件完全不参与匹配 - 执行
php think clear:route是最可靠清除方式；手动删runtime/cache/route.php时，多应用还需同步删各子应用下的对应文件（如app/admin/runtime/cache/route.php） - 注解变更后重建缓存，必须加
--annotation参数：php think route:cache --annotation
最易被忽略的是：注解路由的整个生命周期依赖「扩展安装 → 初始化调用 → 命名空间配置 → 缓存清理」四步闭环，缺一不可；任何一步断在中间，都不会有错误提示，只会让路由彻底消失。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
