hyperf的/metrics端点返回404的根本原因是默认未自动注册该路由，即使metric组件已启用且prometheus驱动配置正确，也必须手动通过router::get('/metrics', ...)->middleware(prometheusmiddleware::class)显式挂载；同时需检查并清除server.php中static_handler_locations对/metrics路径的劫持，否则swoole会跳过路由直接返回404。
Hyperf 的 /metrics 端点为什么返回 404
不是 Prometheus 配置错了，也不是指标没采集——根本原因是 Hyperf 默认不自动注册 /metrics 这个 HTTP 路由。即使 hyperf/metric 已启用、Prometheus 驱动已配置，若没有显式把指标端点挂载到 Swoole 的 HTTP 服务上，请求就会被路由层直接丢弃，返回 404。
必须手动添加路由：用 GET /metrics 绑定指标收集器
Hyperf 的 hyperf/metric 提供了 \Hyperf\Metric\Adapter\Prometheus\PrometheusMiddleware，但它只是中间件，不自动暴露路径；你得自己写一条路由，把请求导向它：
use Hyperf\HttpServer\Router\Router;
use Hyperf\Metric\Adapter\Prometheus\PrometheusMiddleware;
<p>Router::get('/metrics', function () {
return '';
})->middleware(PrometheusMiddleware::class);</p>
注意三点：
-
Router::get('/metrics', ...)必须存在，且路径和metric.php中配置的scrape_path（默认是/metrics）严格一致 - 闭包函数体里写
return ''即可，真实响应由中间件生成，别试图在闭包里 echo 或 return 内容 - 不要用
Router::addRoute或其他非常规方式注册，避免因路由优先级或匹配逻辑导致失效
检查 static_handler_locations 是否劫持了 /metrics
如果你在 config/autoload/server.php 中配置了 static_handler_locations，尤其值包含 / 或 /metrics，Swoole 会把它当成静态文件路径处理，跳过所有路由匹配，直接返回 404 —— 这是 Hyperf 项目里最隐蔽也最高频的 404 原因之一。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
确认并清理该配置：
- 打开
config/autoload/server.php - 搜索
static_handler_locations - 如果值是
['/']或['/metrics']，直接删掉整行或注释掉 - 重启服务生效（
php bin/hyperf.php start）
验证端点是否真正可访问
别只靠浏览器访问 http://127.0.0.1:9502/metrics 看是否返回文本——要确认三件事同时成立：
- Prometheus 抓取时用的 host+port 和你本地访问的一致（看
scrape_host/scrape_port配置） - 该端口未被防火墙或 Docker 网络策略拦截（比如容器内跑 Hyperf，宿主机 curl 不通，很可能是端口没暴露）
- 返回内容第一行必须是
# HELP开头，且无 PHP 错误输出、无空白字符前置——任何额外输出都会导致 Prometheus 解析失败，表现为“抓取成功但无指标”
复杂点在于：路由挂对了、配置清干净了、端口也通了，但返回内容开头多了一个 BOM 或换行，Prometheus 就静默失败。这种问题不会报错，只会让监控看起来“空转”。
