注解失效最常见原因是 scan.paths 漏目录，Hyperf 默认只扫描 BASE_PATH.'/app'，需手动添加如 '/MyApp'、'/Domain' 等路径，并执行 composer dump-autoload -o 和 php bin/hyperf.php di:init-proxy。
scan.paths 漏目录是注解失效最常见原因
Hyperf 默认只扫描 BASE_PATH . '/app'，但你的控制器、注解类、定时任务类很可能不在这个路径下。比如放在 app/Http/Controller、MyApp/Annotation 或 Domain/Service，只要没显式加进 scan.paths，框架连文件都不会读，更别说解析注解。
- 检查
config/autoload/annotations.php中的'paths'数组是否包含你实际存放类的目录，例如：[BASE_PATH . '/app', BASE_PATH . '/MyApp', BASE_PATH . '/Domain'] - Windows 用户必须用正斜杠，
app\Controller是错的，得写成BASE_PATH . '/app/Controller' - 改完配置后必须运行
composer dump-autoload -o，否则自动加载器根本不知道这些类存在 - 如果用了模块化结构（如
MyApp），还得同步更新composer.json的autoload.psr-4映射
SCAN_CACHEABLE=true 但缓存文件缺失 = 静默失败
启用了 SCAN_CACHEABLE 却没生成缓存文件，Hyperf 就会跳过扫描，所有注解等于不存在——而且不报错、不提示，只会 404 或权限校验不触发。
- 首次启用或修改
scan.paths后，必须手动执行php bin/hyperf.php di:init-proxy - 该命令会清空
runtime/container/annotation/并重新扫描、生成注解元数据和代理类 - Docker 构建时，确保
runtime/container/没被.dockerignore过滤，也不能在ENTRYPOINT里删掉再重跑 - 加密部署前，必须保留已生成的
runtime/container/目录及其中所有.php文件
PHP 8 Attributes 写法错一点就静默忽略
Hyperf 3.0 彻底弃用 Doctrine 风格注释（/** @Controller */）和属性类型提示（public UserService $service;）。错用命名参数、漏 use、括号不匹配，都会导致注解不生效，且无日志可查。
- 类级注解必须用命名参数：
#[Controller(prefix: '/api')]，不是#[Controller('/api')] - 方法级同理：
#[GetMapping(path: 'user')]，不是#[GetMapping('user')] - 要用
#[RequestMapping(methods: [RequestMethod::GET])]，就得先use Hyperf\HttpServer\Annotation\RequestMethod -
#[Inject]必须显式写在属性或构造函数参数上，public UserService $userService;不会注入
Finder 扫不到文件的隐蔽情况
即使路径配置正确，Hyperf 的 Symfony\Finder 也可能跳过某些文件，且不报错——AST 解析失败时直接 continue，导致注解收集数量对不上。
- 文件名含空格或非法字符（如
User Service.php）会被 Finder 静默忽略 - 符号链接默认不跟随，需确认 Finder 配置启用了
followLinks() - 文件内容有语法错误（少括号、错标点），Ast 解析器会跳过整个文件
- 快速验证：临时删掉部分文件，观察
AnnotationCollector::getAnnotationsByClass()返回数量是否变化；60 个类只扫到一半，大概率是某几个文件触发了解析异常
注解扫描不是“配完就跑”，它依赖路径、缓存、语法、自动加载四者严丝合缝。任何一环松动，都表现为“注解写了但没反应”，而日志里往往什么都没有。
