注解路由不生效主因是未被扫描到，需检查scan.paths是否包含控制器目录、执行di:init-proxy生成缓存、禁用scan_cacheable或确保runtime/container/annotation/存在有效文件，并严格使用php 8命名参数注解语法。
注解路由不生效，90% 的情况是注解压根没被扫描到，而不是写错了语法——即使 #[Controller] 和 #[GetMapping] 一字不差，只要扫描路径漏了、缓存没生成、或 PHP 8 注解写法不对，框架连文件都不会读。
scan.paths 没包含控制器目录
Hyperf 默认只扫 BASE_PATH . '/app'，但你的控制器可能在 app/Http/Controller、app/Modules/User/Controller，甚至 MyApp/Controller。这些路径必须显式加进 config/autoload/annotations.php 的 scan.paths 数组里：
- 错误写法：
'paths' => ['app/Controller']（相对路径不可靠，Windows 下还可能因反斜杠失效） - 正确写法：
'paths' => [BASE_PATH . '/app/Http/Controller', BASE_PATH . '/MyApp/Controller'] - 改完后必须运行
composer dump-autoload -o，否则类根本不会被加载 - 如果用了自定义命名空间（如
MyApp\Controller），还要同步更新composer.json中的autoload.psr-4
PHP 8 Attributes 写法错误导致静默忽略
Hyperf 3.0 彻底弃用 /** @Controller */ 风格注释，也不识别属性类型提示（如 public UserService $service;）。错一点就 404，且无日志报错：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 类级注解必须带命名参数：
#[Controller(prefix: '/api')]，不是#[Controller('/api')] - 方法级同理：
#[GetMapping(path: 'user')]，不是#[GetMapping('user')] - 必须
use Hyperf\HttpServer\Annotation\Controller;，拼错成Controllor或混用 Laravel 注解会直接失效 - 控制器类名必须以
Controller结尾（如UserController），否则#[AutoController]不生效
SCAN_CACHEABLE=true 但缓存文件缺失
SCAN_CACHEABLE 不是“自动缓存开关”，它只是个条件判断：只有当 runtime/container/annotation/ 下存在合法的 PHP 缓存文件时，才会跳过扫描。而这些文件不会自动生成：
- 首次部署或改完
scan.paths后，必须手动执行：php bin/hyperf.php di:init-proxy - 该命令会清空
runtime/container/并重新扫描、生成注解元数据和代理类 - Docker 构建时，确保
runtime/container/没被.dockerignore过滤，也不能在ENTRYPOINT里删掉再重跑 - 开发环境建议直接设
'cacheable' => false，避免缓存干扰调试
Finder 扫描失败却无提示
Hyperf 用 Symfony\Finder 扫 PHP 文件，但某些情况会静默跳过，你完全不知道它漏了哪些：
- 文件名含空格或非法字符（如
User Service.php）→ Finder 直接忽略 - 目录有符号链接 → 默认不跟随，需在
annotations.php中显式启用followLinks() - 文件内容语法错误（少个括号、
declare位置错）→ Ast 解析失败后continue，不报错也不收集 - 快速验证是否被扫描到：临时删掉部分控制器文件，再执行
php bin/hyperf.php route:list，看输出行数是否变化
最常被忽略的是：di:init-proxy 命令必须在改完配置后立即运行，且 runtime/container/annotation/ 目录权限要可写；另外，route:list 输出为空，不代表没注册成功，而是注解根本没进收集器——先查扫描，再查写法。
