Webgrind仅支持xhprof扩展原生生成的未压缩PHP序列化.xhprof文件；需用file_put_contents直接写入xhprof_disable()返回的数组，确保DATA_DIR可读且文件名以.xhprof结尾。
Webgrind 无法读取 XHProf 生成的 .xhprof 文件？先确认输出格式
Webgrind 默认只认 xhprof 扩展原生生成的、未压缩的 PHP 数组序列化文件（即 serialize() 后的纯文本），不是 JSON，也不是 gzip 压缩过的。如果你用 xhprof_enable() + xhprof_disable() 直接保存，但 Webgrind 显示 “No runs found”，大概率是保存时多做了序列化或压缩。
正确做法是：在调用 xhprof_disable() 后，直接用 file_put_contents() 写入原始数组，不加 serialize()，也不用 json_encode()：
file_put_contents("/tmp/xhprof_run_{$_SERVER['REQUEST_TIME']}.xhprof", xhprof_disable());
注意路径必须可被 Webgrind 的 DATA_DIR 配置访问到，且文件名以 .xhprof 结尾 —— Webgrind 会按此后缀扫描。
Webgrind 报错 “Warning: include(): Failed opening ‘xhprof_lib/utils/xhprof_lib.php’” 怎么办
这是 Webgrind 自带的旧版依赖路径硬编码问题，新版 Webgrind（v1.9+）已移除对 xhprof_lib 的依赖，但很多教程仍让你下载老版本或手动复制 xhprof 源码里的 utils 目录。别这么做。
立即学习“PHP免费学习笔记（深入）”；
解决方案只有两个：
- 从官方 GitHub 下载最新 release（https://www.php.cn/link/4200de485310ff951a2105ea0a9018a7），解压后直接部署，无需额外文件
- 如果必须用旧版，不要 symlink 或复制
xhprof_lib，而是修改config.php中的XHPROF_LIB_PATH为绝对路径，比如：/var/www/webgrind/xhprof_lib（但强烈建议跳过这步，直接换新版）
另外确认 Webgrind 的 config.php 中 DATA_DIR 指向的是你写入 .xhprof 文件的目录，并有读权限（PHP 进程用户能 scandir()）。
为什么 Webgrind 显示的耗时和实际请求时间差很多
Webgrind 只解析 XHProf 的采样数据，它显示的是“函数调用总耗时（inclusive）”，不是 wall-clock 时间。常见偏差来源：
-
xhprof_enable()默认采样间隔是 100μs，太粗略 → 改用xhprof_enable(0, XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY)关闭采样，改用全量记录（仅限低流量调试，否则 I/O 和内存暴涨） - 没过滤掉 autoload、框架初始化等通用逻辑 → 在 Webgrind 界面左上角用
Filter输入your_app_前缀，或提前在采集时用xhprof_disable()返回值做array_filter()清洗 - Webgrind 默认按
wt（wall time）排序，但 XHProf 实际还记录了cpu和mu（memory usage）→ 点击表头切换排序维度，有时cpu更准
PHP 8.x 下 XHProf 不可用？改用 xhprof-extension 或 tideways
原版 Facebook XHProf 已停止维护，PHP 7.4+ 编译会失败。目前可靠方案只有两个：
- 用社区维护版
xhprof-extension（GitHub 上tideways/php-xhprof-extension分支）：支持 PHP 8.0–8.3，安装后函数名仍是xhprof_enable()，完全兼容 Webgrind - 用
tideways（商业版免费基础功能够用）：需改用tideways_enable()，导出格式不同，得配合tideways-phpCLI 工具转成 Webgrind 可读格式，麻烦一倍，不推荐除非你 already use tideways
别信 “用 uopz 模拟 xhprof” 或 “改源码注释掉 zend_parse_parameters” 这类 hack —— 要么崩溃，要么数据错乱。XHProf 的核心是 Zend VM hook，绕不开编译适配。
Webgrind 本身是纯 PHP，不依赖 PHP 版本，但它的输入源头必须是合法的、未损坏的 .xhprof 文件 —— 这个环节最容易被忽略，也是 80% 问题的根因。
