hyperf路由返回404主因是请求未进入路由匹配环节，route:list为空或缺失目标行即为直接证据；需检查注解扫描路径、cacheable配置、psr-4命名规范、static_handler_locations干扰、注解参数细节及composer dump-autoload是否执行。
Hyperf 路由返回 404，八成不是路由写错了，而是请求压根没进到路由匹配环节——php bin/hyperf.php route:list 输出为空或不包含目标行，就是最直接的证据。
route:list 没输出？先确认注解扫描是否启动
Hyperf 默认靠注解注册路由，但扫描链很容易断。常见现象：手动在 config/routes.php 里写死一条 GET /test 能通，但 #[GetMapping("/test")] 就 404。
-
config/autoload/annotations.php中的scan.paths必须显式包含控制器目录，例如['app/Controller']，漏掉路径或拼错（如写成app/controller）会导致扫描跳过 - 开发环境务必设
'cacheable' => false，否则改了注解不重启服务，缓存里的旧路由图谱还在生效 -
#[Controller]和#[GetMapping]必须在同一类中；类名必须严格符合 PSR-4，HelloController.php对应AppControllerHelloController，文件名大小写错（如hellocontroller.php）在 Linux 下直接失效
route:list 有输出但访问仍 404？检查 static_handler_locations 干扰
这是 Hyperf 独有的“静默拦截”坑：一旦 config/autoload/server.php 中配置了 static_handler_locations，且值包含 / 或前缀过宽（如 ['/']），Swoole 会把所有请求当成静态文件处理，根本不会交到 Hyperf 路由器手上——此时 route:list 显示正常，但所有接口全 404。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 临时验证：注释或删除
static_handler_locations配置项，重启服务再试 - 生产环境若需静态资源托管，应限定具体路径，如
['/static', '/uploads']，绝不能填['/'] - 该问题在 Swoole ≥4.5 + view 组件组合下更易触发，但实际影响所有版本
route:list 显示路由存在，但方法/路径不匹配？盯紧注解参数细节
#[GetMapping(path: "/user/{id:d+}")] 这类带约束的注解，匹配失败不会报错，而是直接跳过，结果就是 404。它不像控制器里抛异常，而是在路由层就“视而不见”。
-
path值必须以/开头，"/user/{id}"合法，"user/{id}"不合法（会被当相对路径忽略） - 正则约束部分
{id:d+}中的d+是完整正则表达式，不能写成\d+或d+；斜杠、括号、冒号都必须字面匹配 -
#[PostMapping]不响应 GET 请求，#[GetMapping]不响应 POST，HTTP 方法不一致时返回 405，但前端常误判为 404 - 动态段命名（如
id）要和控制器方法参数名一致：public function view(int $id)才能自动注入；名字对不上就拿不到值，但路由仍算匹配成功
为什么 curl 通了但 route:list 没显示？别忽略 composer dump-autoload
Hyperf 注解扫描依赖自动加载映射。如果新增了控制器类但没更新 autoload，route:list 就扫不到——哪怕文件已存在、类定义语法完全正确。
- 执行
composer dump-autoload强制刷新 PSR-4 映射，比删vendor/autoload.php更安全有效 - 某些 IDE 或编辑器保存时未触发文件系统事件，导致 Hyperf 的注解扫描器读到旧文件列表，重启
php bin/hyperf.php start是必要操作 - 检查
composer.json中autoload.psr-4是否覆盖了你的控制器命名空间，例如"App\": "app/"缺失会导致整个App\Controller不被识别
真正卡住人的从来不是“怎么写路由”，而是“为什么写的没被看见”。route:list 是唯一可信源，但它只反映当前加载状态——路径、缓存、autoload、Swoole 静态路由配置，任何一个环节掉链子，它就变成一张废纸。
