Hyperf项目无法安装php-skywalking扩展，因该扩展v2.x仅支持cli/fpm SAPI，不兼容swoole协程模式，强行安装会导致Segmentation fault；应改用apache/skywalking-php SDK（v1.x起支持Hyperf 3.0+），通过Hook+Coroutine\Channel实现协程安全埋点，并手动配置DB/Redis/Guzzle等Hook及sw8上下文透传。
Hyperf项目里装不上php-skywalking扩展？先确认SAPI类型
Hyperf默认运行在swoole协程模式下，而php-skywalking扩展（v2.x）仅支持cli和fpm SAPI，不兼容swoole——这是集成失败最常卡住的地方。强行编译安装后，启动php bin/hyperf.php start会直接报Segmentation fault或静默退出。
实操建议：
- 检查当前PHP SAPI：
php -r "echo PHP_SAPI;"，若输出swoole，说明你正在用Hyperf的常驻进程模式，php-skywalking扩展不可用 - 不要尝试用
pecl install php-skywalking硬装；该扩展未实现协程安全的Tracer上下文切换，底层依赖zend_execute_ex钩子，在Swoole协程中会破坏调用栈 - 如必须用原生扩展，只能退回到FPM模式启动Hyperf（失去协程优势），且需关闭
opcache.enable_cli=1，否则Tracer初始化失败
用skywalking-php SDK替代扩展：适配Hyperf协程
php-skywalking扩展走不通，应切换到纯PHP实现的skywalking-php SDK（注意命名差异：无连字符，GitHub仓库为apache/skywalking-php）。它通过Hook + Coroutine\Channel管理Span生命周期，天然支持Swoole协程上下文透传。
关键步骤：
立即学习“PHP免费学习笔记（深入）”；
- 安装SDK：
composer require apache/skywalking-php:^1.0（v1.x起支持Hyperf 3.0+） - 在
config/autoload/tracer.php中配置：'enable' => true、'collector' => '127.0.0.1:11800'（对应SkyWalking OAP地址） - 注册Hyperf全局中间件，在
src/Middleware/TracingMiddleware.php中调用Tracer::startRootSpan()并finish()，确保HTTP请求Span闭合 - 注意
max_buffer_size参数，默认300太小，高并发下易丢Span；建议设为3000并配合report_interval（单位秒）平衡性能与实时性
Hyperf DB/Redis/Guzzle调用没被自动埋点？补全Hook配置
skywalking-php SDK默认只Hook了curl_exec和pdo_query，但Hyperf常用Hyperf\Database、Hyperf\Redis、GuzzleHttp\Psr7\Request等组件，需手动启用对应Hook。
配置要点：
- DB：在
tracer.php中开启'hooks' => ['pdo', 'mysql', 'pgsql']，Hyperf的DbConnection底层仍走PDO，无需额外适配 - Redis：必须显式添加
'redis'到hooks数组，否则$redis->get()等操作不会上报；注意SDK v1.2+才支持Predis\Client和Hyperf\Redis\Redis - Guzzle：启用
'guzzle'Hook后，仅拦截GuzzleHttp\Client::request()，若项目用Hyperf\HttpClient，需自行封装HttpClient调用并手动创建ExitSpan - 所有Hook函数均在
co\run协程内执行，避免在onWorkerStart等非协程上下文中调用Tracer::startSpan()
Span数据发不到OAP？检查gRPC连接与元数据注入
常见现象是服务在SkyWalking UI里可见，但无Trace链路，点开全是“Empty trace”。根本原因通常是gRPC连接建立失败，或客户端未正确注入sw8上下文头。
排障重点：
- 用
telnet 127.0.0.1 11800确认OAP gRPC端口可达；若超时，检查OAP配置core.defaultModulePlugin.grpcConfig.host是否绑定0.0.0.0而非127.0.0.1 - Hyperf HTTP客户端默认不透传
sw8头，需在发起请求前手动注入：$headers['sw8'] = Tracer::getCtx()->serialize(); - 若使用
Hyperf\Rpc，需在Consumer端beforeInvoke事件中调用Tracer::inject()，否则下游服务无法续接Span - OAP日志中出现
Invalid segment buffer，大概率是SDK版本与OAP版本不匹配（如SDK v1.0对接OAP v9.4+需升级SDK至v1.3+）
Hyperf里做分布式追踪，真正的难点不在埋点本身，而在协程上下文与Span生命周期的严格对齐——漏掉一次finish()，整个链路就断在那了。
