webgrind怎么安装使用 webgrind分析xdebug日志教程-php教程-PHP中文网

webgrind本身不采集性能数据，仅读取xdebug生成的cachegrind.out.*文件；常见“没数据”问题源于xdebug未正确生成文件、$profilerdir路径不一致或权限不足。

webgrind怎么安装使用 webgrind分析xdebug日志教程

Webgrind 本身不采集性能数据，它只读取 Xdebug 生成的 cachegrind.out.* 文件。装错顺序（比如先配 Webgrind 再配 Xdebug）或路径不一致，90% 的“打不开”“没数据”问题就出在这儿。

确认 Xdebug 已生成 cachegrind 文件

这是前置硬条件。Webgrind 启动后根本不会报错，但界面空着——往往是因为根本没文件可读。

xdebug.profiler_enable=1 会为每个请求都生成分析文件，适合本地调试；更推荐用 xdebug.profiler_enable_trigger=1，然后加 ?XDEBUG_PROFILE 参数手动触发（注意：不是 ?XDEBUG_PROFILE:，多一个冒号就失效）
xdebug.profiler_output_dir 必须是 Web 服务器进程（如 www-data、nginx、_www）有**写权限**的目录，常见设为 /tmp，但 macOS 或某些 Docker 环境里 /tmp 可能被隔离，建议显式设为 /var/tmp 或项目内 ./xdebug-profiler
改完 php.ini 后，必须重启 PHP-FPM 或 Apache/Nginx，仅 reload 不生效；验证方式：访问 phpinfo() 页面，搜索 “xdebug”，确认 profiler_enabled 显示为 On，且 profiler_output_dir 路径与你预期一致
执行一次带触发参数的页面（如 http://localhost/test.php?XDEBUG_PROFILE），立刻去 profiler_output_dir 下看是否生成了 cachegrind.out.* 文件（文件名末尾是进程 PID）

Webgrind 部署路径和 config.php 关键配置

Webgrind 是纯 PHP 前端，没有后端服务，但对目录权限和配置路径极其敏感。

Xdebug 3.4.1

Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有

下载

把 Webgrind 解压后整个目录放到 Web 服务器可访问路径下（如 /var/www/html/webgrind），确保 index.php 能被直接访问（http://localhost/webgrind）
编辑 config.php，重点改三处：
– $profilerDir：必须和 Xdebug 的 profiler_output_dir **完全一致**，不能留空，也不能写成相对路径
– $storageDir：Webgrind 解析后缓存聚合数据的目录，需可写（如 /tmp/webgrind-cache），否则每次点 “update” 都重新解析大文件，卡死
– $defaultCostformat：建议设为 'msec'，比 'percent' 更直观，避免误判“某个函数只占 0.3% 所以不重要”，其实它耗了 800ms
如果用 PHP 内置服务器测试（php -S 0.0.0.0:8080 index.php），$profilerDir 必须是绝对路径（/tmp 有效，../tmp 无效）

Docker 启动时挂载路径必须精准对应

很多人用 docker run -v ./xdebug:/tmp，结果 Webgrind 还是看不到文件——因为 Xdebug 实际写入的是容器内的 /tmp，而你挂载的宿主机目录可能根本没生成文件。

先确认 Xdebug 在哪生成文件：在 PHP 中运行 echo ini_get('xdebug.profiler_output_dir');
Docker 命令中 -v 的左侧（宿主机路径）必须是你真正看到 cachegrind.out.* 的地方；右侧（容器内路径）必须和 config.php 里的 $profilerDir 以及 Xdebug 的 profiler_output_dir **三者完全一致**
官方镜像 jokkedk/webgrind:latest 默认读 /tmp，所以命令应为：
docker run --rm -v /host/path/to/cachegrind:/tmp -p 8080:80 jokkedk/webgrind:latest
容器启动后，进容器执行 ls /tmp/cachegrind.out.*，确保文件真实存在

打开 Webgrind 后没数据？先检查这三点

界面右上角点 “update” 没反应，或下拉菜单空，不是 Webgrind 坏了，而是数据链断在某个环节。

浏览器开发者工具 Network 标签页里，看 index.php?op=getFiles 请求是否返回 200 且响应体是 JSON 数组；如果是 500，大概率是 $profilerDir 权限不够或路径不存在
查看 Webgrind 日志（如果开了 error_log）或 PHP 错误日志，搜 Warning: scandir 或 Permission denied，直指目录问题
别忽略时区：如果 $defaultTimezone 设错（如 Europe/Copenhagen），可能导致文件按时间排序异常，最新生成的文件排在最后几页，你以为“没数据”，其实要翻好几页才看到

最常被跳过的动作：改完 config.php 或 php.ini 后，没清浏览器缓存就反复刷新 Webgrind 页面——它会缓存旧的文件列表。关掉标签页重开，或强制刷新（Cmd+Shift+R / Ctrl+F5）。