PHP Profiler 配合 Composer 使用时，90% 报错源于扩展、配置、启动时机三者未对齐：composer require 仅安装类库，需手动安装并启用底层 C 扩展（如 tideways_xhprof），确保 php.ini 正确加载且路径、SAPI、命名严格匹配；XHGui 数据上传失败多因 URL、token 或网络策略配置错误；启动代码必须置于业务逻辑之前，顺序错则全程漏采。
直接装不上、装了没效果、数据不上传——这三个问题占了 PHP Profiler 配合 Composer 使用时 90% 的报错来源。核心原因不是命令输错了，而是扩展、配置、启动时机三者没对齐。
composer require 后为什么 profiler 没生效？
因为 composer require 只下载 PHP 类库，不自动加载扩展（.so/.dll）。Profiler 要起作用，必须有底层 C 扩展支持（如 tideways_xhprof、xhprof 或 forp）。
- 先确认扩展是否已编译并启用：
php -m | grep -i xhprof或php -m | grep -i tideways - 若无输出，需手动安装扩展：Linux 下用
pecl install tideways_xhprof，Windows 下下载对应.dll并在php.ini中加extension=tideways_xhprof -
perftools/php-profiler和aterrien/forp-profiler这类包本身不带扩展，只提供封装逻辑，缺扩展就等于没引擎
php.ini 中 extension=xxx.so 加了但 still not working？
常见于路径错误、PHP SAPI 不匹配、或扩展被其他配置屏蔽。
- 用
php --ini确认当前 CLI 读取的是哪个php.ini；Web 环境（如 Apache/Nginx）可能用另一份，需单独检查 - 扩展名必须严格匹配：比如
tideways_xhprof.so不能写成tideways.so；Windows 下是.dll，不是.so - 某些环境（如 Docker）默认禁用
dl()函数，导致运行时加载失败，必须静态启用（即写进php.ini） - 扩展依赖 OpenSSL/curl，若
php -v报 warning，先解决基础扩展缺失问题
Profiler 数据无法发送到 XHGui？
多数情况是配置中 URL、token、超时参数未对齐，或网络策略拦截 POST 请求。
立即学习“PHP免费学习笔记（深入）”；
-
save.handler.upload.url必须是 XHGui 的/run/import接口地址，不是首页 URL；末尾斜杠不能少 -
token值需与 XHGui 配置的XHGUI_AUTH_TOKEN完全一致（大小写敏感） - 若用 Nginx，检查是否限制了请求体大小：
client_max_body_size 20M;，否则大 profile 数据被截断 - 开发环境可临时把
save.handler改为Xhgui\Profiler\Profiler::SAVER_FILE，看是否生成本地文件，快速定位是采集问题还是传输问题
最易被忽略的一点：Profiler 启动代码必须放在所有业务逻辑之前，且不能被条件分支包裹（除非你明确知道哪些请求该采样）。比如在 Laravel 的 public/index.php 里，它得出现在 require __DIR__.'/../vendor/autoload.php'; 之后、require_once __DIR__.'/../bootstrap/app.php'; 之前——顺序错一点，整个请求生命周期就漏掉了。
