Xdebug 3 已加载且配置路径正确需确认CLI与Web SAPI使用同一php.ini，通过php --ri xdebug验证Enabled及mode=profile，并设xdebug.start_with_request=trigger、output_dir权限正确。
确认 Xdebug 3 已加载且配置路径正确
很多人配完 xdebug.mode=profile 却没生成任何文件，根本原因往往是改错了 php.ini —— PHP CLI 和 Web SAPI（如 FPM）可能用完全不同的配置文件。在 PhpStorm 中按 Ctrl+Alt+S → PHP → CLI Interpreter → 右侧“Configuration file”显示的路径，才是你真正要编辑的那个文件；FPM 还得额外检查 /etc/php/*/fpm/php.ini 或 www.conf 里是否启用了该扩展。运行 php --ri xdebug，看到 Enabled 且 mode => profile 才算到位。
必须同时设置两个启动条件才能触发 Profiling
Xdebug 3 不再靠单个开关控制 Web 请求的 profiling 行为。只设 xdebug.mode=profile 是不够的，它默认只对 CLI 生效。你还得加： xdebug.start_with_request=trigger。这样浏览器访问时带上 ?XDEBUG_PROFILE=1 或手动设置 Cookie XDEBUG_PROFILE=1，才会真正写入文件。别用 xdebug.start_with_request=yes，那会每次请求都生成，磁盘和性能开销都不可控。
输出目录权限和路径必须由 Web 进程可写
xdebug.output_dir="/tmp/xdebug" 这个路径得存在，且 Web 服务器进程（比如 www-data、nginx 或 php-fpm 用户）有写权限。常见错误是目录存在但属主不对，ls -ld /tmp/xdebug 看一眼就知道。推荐用：sudo mkdir -p /tmp/xdebug && sudo chown www-data:www-data /tmp/xdebug（根据实际用户调整）。别用 chmod 777，既不安全也掩盖了权限模型问题。
用 PhpStorm 正确打开 cachegrind 文件而不是双击
生成了 cachegrind.out.12345 后，直接双击或拖进 PhpStorm 会失败或乱码——因为 PhpStorm 不识别原始格式。必须走专用入口：菜单栏 Tools → Analyze Xdebug Profiler Snapshot，然后手动选中那个文件。打开后默认是 Flat View，要看调用链必须切到 Call Tree；重点关注 Inclusive Time（含子调用）和 Exclusive Time（纯自身耗时），比如某个 PDO::query() 的 Inclusive 很高但 Exclusive 很低，说明瓶颈不在 PDO 本身，而在它执行的 SQL 或后续处理逻辑里。
立即学习“PHP免费学习笔记（深入）”；
最常被忽略的一点：Xdebug Profiler 只记录 PHP 函数级耗时，它告诉你 curl_exec() 花了 800ms，但不会告诉你卡在 DNS 解析、TLS 握手还是远端响应慢；它显示 mysqli_query() 耗时长，但不指出是没走索引还是锁等待。真要定位这类问题，得配合 strace、MySQL 的 slow log 或 Blackfire 这类能穿透到系统调用层的工具。
