最常见原因是Web请求未触发profiler：Xdebug 3默认关闭所有功能，必须同时配置xdebug.mode=profile和xdebug.start_with_request=trigger，并在URL加?XDEBUG_PROFILE=1或设置对应Cookie，且确保Web进程用户对xdebug.output_dir有写权限。
为什么 cachegrind.out.* 文件根本没生成
最常见原因不是 Xdebug 没装好，而是 Web 请求压根没触发 profiler。Xdebug 3 默认关闭所有功能，xdebug.mode=profile 单独设了没用，必须同时配 xdebug.start_with_request=trigger ——否则只对 CLI 生效，Apache/Nginx 下的请求完全静默。
检查点清单：
- 确认你改的是 PHP-FPM 或 Apache 实际加载的
php.ini：在 PhpStorm 里按Ctrl+Alt+S → PHP → CLI Interpreter → Configuration file显示的路径才是真配置文件 - 运行
php --ri xdebug，输出里必须同时看到mode => profile和start_with_request => trigger - 浏览器访问时必须带
?XDEBUG_PROFILE=1（大小写敏感），或手动设置 Cookie：XDEBUG_PROFILE=1 -
xdebug.output_dir目录（如/tmp/xdebug）要确保 Web 进程用户（如www-data、nginx）有写权限，sudo chown -R www-data:www-data /tmp/xdebug比chmod 777更安全
php -m 看到 xdebug，但 phpinfo() 里没 profiler 配置
说明你可能改错了配置文件：CLI 和 Web SAPI 使用不同 ini 文件。比如 Ubuntu 上 PHP-FPM 通常用 /etc/php/*/fpm/php.ini，而 php -m 走的是 CLI 的 /etc/php/*/cli/php.ini。两个地方都要检查 xdebug.mode 和 xdebug.start_with_request 是否一致启用。
快速验证法：
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 在 Web 页面里放
<?php phpinfo(); ?>，搜索xdebug.mode和xdebug.output_dir，看值是否符合预期 - 命令行执行
php -r "echo ini_get('xdebug.mode');"，对比 Web 环境输出 - 若不一致，就说明 Web SAPI 没读到你的修改，去对应 SAPI 的 ini 目录补上配置
生成了 cachegrind.out.* 但 PhpStorm 打不开或报错
不是文件损坏，是打开方式错了。PhpStorm 不支持直接双击打开 cachegrind 文件，必须走专用入口。
正确流程：
- 菜单栏选
Tools → Analyze Xdebug Profiler Snapshot（不能用 Open File） - 打开后默认是
Flat View，只显示函数总耗时；切到Call Tree才能看到完整调用链，比如Controller::index() → Service::fetchData() → PDO::query() - 如果提示 “file is compressed”，检查
xdebug.use_compression=0—— Xdebug 3 默认开启压缩，生成.gz后缀文件，PhpStorm 和 QCacheGrind 都不认
命令行脚本怎么触发 profiler
HTTP 请求能加 ?XDEBUG_PROFILE=1，但 CLI 下不行。Xdebug 3 不支持通过环境变量或参数动态触发 profiling，必须显式启用：
- 临时启用：
XDEBUG_MODE=profile php script.php - 永久启用（仅限调试）：
php -d xdebug.mode=profile script.php - 注意：CLI 下
xdebug.start_with_request无效，它只作用于 Web 请求生命周期
容易被忽略的是：CLI 和 Web 的 xdebug.output_dir 可以不同，但目录权限逻辑一样——确保当前执行用户（如你的 shell 用户）对该目录有写权，否则文件生成失败且无提示。
