注解失效主因是环境与组件版本不兼容：php≥8.1、swoole启用协程、执行composer dump-autoload；hyperf/annotation等组件须统一为^3.1.x，config/autoload/annotations.php中paths需显式配置如['app/controller']，且cacheable设为false。
更新 Hyperf 3.1 的过程中出现注解组件不兼容报错，核心原因不是版本号没升上去，而是注解扫描链在新旧版本间断裂或冲突——比如 hyperf/annotation、hyperf/di、hyperf/aop 这几个关键组件版本不齐，或与 PHP/Swoole 环境不匹配，直接导致 @AutoController、@GetMapping 失效，甚至启动报 Class not found 或静默退出。
先确认三道硬性门槛是否全部过关
90% 的“更新后注解失效”其实卡在基础环境没达标：
- PHP 版本必须 ≥ 8.1 —— Hyperf 3.1 已弃用 PHP 8.0 及以下，低版本下协程注解扫描器根本不会初始化
- Swoole 必须启用协程支持：运行
php --ri swoole，输出中必须含 support coroutines: enabled；若显示disabled或压根没这行，说明加载的是系统旧版（如 Swoole 4.x），需重装 Swoole 5.0+ 并确认extension=swoole.so指向正确路径 - 首次启动前必须执行
composer dump-autoload（开发）或composer install --no-dev（生产）—— 注解依赖类自动加载，不刷新 autoload 就等于没注册控制器
检查注解相关组件是否版本对齐
Hyperf 3.1 要求所有官方注解链组件保持主版本一致，混搭 v2 和 v3 组件是典型冲突源：
- 运行
composer show hyperf/annotation hyperf/di hyperf/aop hyperf/http-server，确认它们都是 ^3.1.x（不是 ^3.0 或 ^3.2，更不能是 ^2.x） - 重点查
hyperf/annotation：它负责解析@AutoController等元数据，若被其他包间接降级（例如某个 dev 依赖锁死了hyperf/utils:^2.0），就会让注解扫描器加载失败 - 用
composer depends --tree hyperf/annotation查谁在拖后腿；再用composer why-not hyperf/annotation:^3.1.0定位具体阻塞包
注解路由不生效？重点核对配置项
即使组件装对了，配置写错一行也会让注解“隐身”：
-
config/autoload/annotations.php中的'paths'必须显式列出控制器目录，例如['app/Controller']；写成['app']不会递归扫描，IndexController就永远不会被发现 -
'cacheable'开发时务必设为false，否则改了注解不重启服务，缓存里的旧扫描结果一直生效，你会误以为“代码没起作用” - 控制器类命名必须严格符合 PSR-4：文件
app/Controller/IndexController.php对应命名空间App\Controller\IndexController，大小写、路径、命名空间缺一不可
升级后启动报错 Class not found 或 Segmentation fault
这不是代码问题，是环境或加载顺序崩了：
- Segmentation fault 大概率是 Swoole 协程未启用 + Hyperf 强制调用协程 API，立刻检查
php --ri swoole - Class not found 常见于
hyperf/di版本低于hyperf/annotation，导致容器无法注入注解处理器；统一升级命令推荐：composer update hyperf/annotation hyperf/di hyperf/aop hyperf/http-server --with-dependencies - 如果用了自定义注解或第三方 AOP 扩展，检查其是否声明了
hyperf/annotation的版本约束；冲突时优先移除非官方扩展，验证基础注解是否恢复
