必须安装hyperf/annotation和hyperf/http-server组件，并在annotations.php中启用scan=>true且正确配置paths路径，否则注解路由不生效。

确认是否已安装必要组件

注解路由不是开箱即用的，必须显式安装 hyperf/annotation 和 hyperf/http-server。缺一不可——前者提供注解解析能力，后者提供 HTTP 路由调度支持。

• 运行 composer show hyperf/annotation 和 composer show hyperf/http-server 确认已安装
• 若未安装，执行 composer require hyperf/annotation hyperf/http-server
• 注意：Hyperf 3.x 默认不包含 hyperf/annotation，即使创建项目时选了“完整版”，也需手动装

启用 annotations.php 中的 scan 配置

Hyperf 不会自动扫描注解，必须在 config/autoload/annotations.php 中打开开关并指定路径，否则所有 #[Controller]、#[GetMapping] 都会被忽略。

• 确保该文件中 'scan' => true 已设置（不是注释掉）
• 'paths' 必须包含控制器目录，例如 ['app/Controller']；如果控制器在 app/Http/Controllers，就得写对应路径
• 路径必须是相对于项目根目录的，且不能以 / 开头（'/app/Controller' 是错的）
• 修改后需重启服务（Swoole Worker），仅 reload 不生效

@AutoController 和 @Controller 的选择差异

两者都依赖注解扫描，但行为不同，选错会导致路由注册失败或路径不符合预期。

hyperframes-超帧视频

HTML 驱动的视频合成——GSAP 动画、TTS 字幕、音频响应、着色器转场

下载

• #[AutoController]：按方法名自动生成路由，如 index() → /controller-name/index；默认只支持 GET/POST，不支持中间件配置
• #[Controller]：必须配合 #[GetMapping] 等方法级注解使用；支持 prefix 参数，也支持 middleware 选项（如 #[Controller(middleware: [AuthMiddleware::class])]）
• 别混用：一个类上同时写 #[AutoController] 和 #[Controller] 会冲突，优先级未定义，实际行为取决于扫描顺序

验证注解是否真正生效

光写注解不等于路由注册成功。常见“写了但 404”问题，往往卡在扫描环节或命名空间错误。

• 执行 php bin/hyperf.php route:list，检查输出中是否出现你期望的路径（如 GET /user/info）
• 若列表为空，说明扫描没触发——回看 annotations.php 的 scan 和 paths
• 若路径存在但访问 404，检查控制器类是否用了正确的命名空间（必须是 App\Controller\* 或你在 paths 中声明的命名空间前缀）
• PHP 8+ 强烈推荐用 Attributes（#[GetMapping]），而非 DocBlock（/** @GetMapping */）；后者在 IDE 或反射中容易被忽略，且不支持类型提示校验

注解路由真正的门槛不在语法，而在「扫描是否启动」和「路径是否被纳入扫描范围」——这两点漏掉任何一个，代码写得再标准也没用。