hyperf注解失效主因有四：1.扫描路径未包含自定义目录；2.php8+属性类型提示不被识别，须用#[inject]显式注解；3.finder因文件名、符号链接或语法错误跳过文件；4.枚举类热更新时注解缓存未刷新。

注解类没被扫描到，scan.scan_dirs 配置漏了路径

Hyperf 默认只扫描 BASE_PATH . '/app'，如果你把类放在 MyApp、Modules 或 Domain 这类自定义目录下，不显式加进扫描路径，注解就完全不会被解析。

检查 config/autoload/annotations.php 中的 scan.paths 是否包含你的实际目录：

• 错误写法：'paths' => [BASE_PATH . '/app']
• 正确写法：'paths' => [BASE_PATH . '/app', BASE_PATH . '/MyApp', BASE_PATH . '/Domain']

改完别忘了运行 composer dump-autoload -o 更新自动加载映射，否则即使路径对了，类也根本不会被 PHP 加载进来。

@Inject 属性注入不生效，其实是注解没写对

PHP 8.0+ 的属性类型提示（如 public UserService $userService;）Hyperf 完全不识别——它只认 #[Inject] 这类显式注解。

常见错误和对应写法：

• 漏写注解：public UserService $userService; → 不会注入
• 错用注释：// @Inject public UserService $userService; → 注释不是注解，无效
• 正确写法（属性）：#[Inject] public UserService $userService;
• 正确写法（构造函数）：public function __construct(#[Inject] UserService $service) { }

注意：如果类本身没被扫描（比如没加 @Service 或其他有效注解），即使写了 #[Inject]，容器也不会注册它，后续注入自然失败。

注解收集器里查不到类，Finder 没读到文件

Hyperf 用 Symfony\Finder 扫描 PHP 文件，但某些情况会导致文件被跳过：

• 文件名含非法字符或空格（如 User Service.php），Finder 可能静默忽略
• 目录嵌套过深或符号链接未启用（followLinks() 默认关）
• 文件内容语法错误（哪怕只是少个括号），Ast 解析失败后直接 continue，不报错也不收集

快速验证是否被扫描到：在 ReflectionManager::getAllClasses() 中加一行日志，或临时删掉部分文件，看注解收集数量是否变化。60+ 个类同目录下只扫到一半？大概率是某几个文件触发了解析异常，逐个排查更高效。

热更新时枚举类注解失效，缓存没刷新

PHP 8.1+ 枚举类（enum）的注解在 server:watch 下容易卡在旧缓存里，尤其当修改的是 #[OA\Property] 这类嵌套在 case 上的注解。

这不是配置问题，而是 Watcher 组件对枚举结构的元数据重载不完整。临时绕过方法：

• 停掉 server:watch，改用 server:start 启动，再手动 kill -USR1 触发 reload
• 强制清空注解缓存：rm -rf runtime/container/annotation，再重启服务
• 生产环境务必禁用 watch，所有注解变更必须走完整构建流程

真正麻烦的是 case 级注解——它们不参与 DI 容器注册，只用于文档生成等场景，一旦热更新没刷进去，Swagger 就显示空描述，但代码逻辑不受影响。这点容易误判为“功能坏了”，其实只是展示层断连。