必须启用注解扫描且路径正确：config/autoload/annotations.php中scan设为true，paths包含app/Controller；开发时cacheable设为false；推荐用#[AutoController]声明控制器。
想在Hyperf 3.1项目中正确写出能被访问的注解路由控制器，又怕改了代码却始终404、route:list查不到、或服务重启后注解不生效？这通常不是代码写错了，而是注解扫描链某个环节断开了。
确认注解扫描已启用且路径配置正确
打开 config/autoload/annotations.php 文件，检查 scan 配置项是否为 true，并确认 'paths' 数组中包含你的控制器目录，例如 'app/Controller'。
如果 'scan' => false 或 'paths' 为空/未包含 app/Controller，注解将完全被忽略——【这是90%的404根本原因】。
开发阶段务必设置 'cacheable' => false，否则修改注解后不重启服务，旧缓存会持续生效。
选择控制器声明方式：AutoController 还是 Controller + 方法注解
方法一：用 #[AutoController] 快速启动
在 app/Controller/IndexController.php 中写：
namespace App\Controller;
use Hyperf\HttpServer\Annotation\AutoController;
#[AutoController(prefix: '/api')] // 注意：不要写成 '/api/'
class IndexController {
public function index() { return ['code' => 0, 'msg' => 'ok']; }
}
方法二：用 #[Controller] + #[GetMapping] 精确控制
同样在 IndexController.php 中写：
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
#[Controller(prefix: '/api')]
class IndexController {
#[GetMapping(path: '/health')]
public function health() { return ['status' => 'up']; }
}
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
注意：#[Controller] 和 #[GetMapping] 必须在同一类中；类名必须严格匹配 PSR-4 规则（如文件名为 IndexController.php，则类必须为 App\Controller\IndexController）。
验证路由是否真实注册成功
第一步：执行命令查看已加载路由
在项目根目录运行：php bin/hyperf.php route:list
输出中必须出现类似这一行：GET | /api/index | App\Controller\IndexController::index，才说明注解已被扫描并注册。
第二步：临时移除控制器文件，触发404
将 IndexController.php 重命名为 IndexController.php.bak → 启动服务（或确保已重启）→ 执行 curl http://127.0.0.1:9501/api/index → 返回 404 即证明原路由确实由该控制器提供。
第三步：若 route:list 无输出或 curl 始终空响应，立即检查：【是否执行过 composer dump-autoload】，以及 config/autoload/annotations.php 中 scan.paths 是否拼写错误（比如写成 app/Controllers）。
启动服务并访问接口
确保项目已安装 hyperf/http-server 和 hyperf/annotation 组件。
在项目根目录执行：php bin/hyperf.php start
服务默认监听 127.0.0.1:9501，此时访问 http://127.0.0.1:9501/api/index（或你定义的 path）即可看到 JSON 响应。
