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 就显示空描述，但代码逻辑不受影响。这点容易误判为“功能坏了”，其实只是展示层断连。
