Hyperf中Zipkin链路追踪需显式配置driver为'zipkin'、正确设置endpoint_url和timeout、启用TraceMiddleware与对应Aspect，否则数据无法上报。
Hyperf 中用 Zipkin 做链路分析，关键不是装了 hyperf/tracer 就完事——opentracing.php 配置错一个字段，数据就发不出去，UI 里永远空白。
driver 必须设为 'zipkin'，且顶层配置不能漏
Hyperf 的 tracer 组件默认不激活任何驱动，'default' => env('TRACER_DRIVER', 'zipkin') 这行必须存在，且环境变量 TRACER_DRIVER 要显式设为 zipkin。如果写成 jaeger 或留空，Zipkin 配置块会被完全忽略，连初始化都不触发。
-
config/autoload/opentracing.php中的'zipkin'键必须在'tracer'下一级，不能嵌错层级 - 别把
'driver' => ZipkinTracerFactory::class写到'jaeger'块里——Jaeger driver 不认这个字段 - 若同时配了 zipkin 和 jaeger，只启用其中一个，避免混淆
endpoint_url 和 timeout 是唯二必须校验的上报参数
'endpoint_url' 必须指向 SkyWalking OAP 的 Zipkin receiver（如 http://skywalking-oap:9411/api/v2/spans），不是 Jaeger 的 UDP 地址，也不是 Collector 的 gRPC 接口。HTTP 上报依赖连接池和超时控制，'timeout' 设太小（如 0.1）会导致 span 丢弃无提示。
- 测试阶段可用
http://localhost:9411/api/v2/spans，但容器内要确保能解析localhost到宿主机（推荐用 host.docker.internal 或显式 IP） -
ZIPKIN_ENDPOINT环境变量值必须带完整路径/api/v2/spans，少写会返回 404 且 tracer 不报错 - 别用
https协议除非 OAP 明确启用了 TLS，否则请求静默失败
app 配置决定服务在 UI 中的显示名和拓扑位置
'app' 数组里的 'name'、'ipv4'、'port' 会生成 Zipkin 的 Endpoint，直接影响 SkyWalking UI 中的服务名、IP 标签和端口归属。填错会导致多个实例被聚合成一个“未知服务”或分散在不同节点下。
-
'name'建议用env('APP_NAME')，且各服务间不能重复（如都写hyperf-service） -
'ipv4'在 Kubernetes 中应设为env('POD_IP')，不是127.0.0.1；本地开发可固定为127.0.0.1 -
'port'要与 Hyperf 实际监听端口一致（如9501），否则拓扑图里服务端口显示错误
自动追踪依赖中间件 + Aspect，缺一不可
仅配好 opentracing.php 不会自动埋点。HTTP 入口靠 TraceMiddleware 拦截并创建根 Span；Guzzle、Redis、Db 等调用靠对应 Aspect 类拦截并续传上下文。任一缺失，链路就会断在某一层。
-
config/autoload/middlewares.php中必须注册\Hyperf\Tracer\Middleware\TraceMiddleware::class -
config/autoload/aspects.php要确认包含\Hyperf\Tracer\Aspect\HttpClientAspect::class等关键切面 - JsonRPC、gRPC 等非 HTTP 协议需额外配置对应
Aspect（如GrpcAspect），否则调用链止步于第一个 HTTP 服务
最容易被忽略的是：Zipkin 上报走 HTTP，但 Hyperf 默认不开启 Guzzle 的异步重试，网络抖动时单个 span 可能丢失；而 tracer 层既不重发也不打日志，你只能在 SkyWalking UI 里看到“断层”的 Trace —— 所以上线前务必用 curl -v http://skywalking-oap:9411/api/v2/spans 验证连通性，再看 UI 是否实时出现新 trace。
