PHP 调试 - Xdebug

article/2025/9/28 19:49:07

PHP 调试指南.pdf
PHP 程序员的调试技术

根据要调试的对象的不同，采取的方法也不一样：

调试 web 应用：对于 web 应用，可以在浏览器中安装插件，或者在 IDE 中设置，下面的设置二选一即可。
- Get/Post 请求或 Cookie 中添加 XDEBUG_SESSION_START=session_name，使 Xdebug 知道这个请求应该连接 IDE 进行调试。一般由 IDE 提供这个功能。
- 安装浏览器插件。
调试其他应用：调试命令行程序或者单元测试时，不需要在浏览器中查看效果，则省去了上面的步骤。

下载并开启 Xdebug

通过 Xdebug，可以在 IDE 的终端进行调试，可以单步调试、查看调用栈和变量值。此外，Xdebug 还可以分析性能（XHProf 也可以分析性能）。

Xdebug 支持的功能有：

远程调试，原文参考：https://xdebug.org/docs/remote，译文参考：https://segmentfault.com/a/1190000011332021
trace 代码跟踪：trace 日志记录代码执行流程，包括时间索引、内存使用、内存增量、函数名称参数、文件名文件行等信息
profile 性能探查：profile 日志记录函数的执行耗时和调用关系

下载安装

下载地址：https://xdebug.org/download.php

我用的 PHP 是 7.2，64位，非线程安全的版本，所以下载 PHP 7.2 VC15 (64 bit) 这个版本的 Xdebug。

下载完成后，将其放入 PHP 安装目录下的 ext 目录。然后修改 php.ini 文件（或者专门建立独立的 ini 配置文件给 Xdebug 用）添加如下内容：

[Xdebug]
zend_extension="c:/php/ext/php_xdebug-2.1.0-5.3-vc6.dll"
xdebug.remote_enable=true
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9001

通过命令行执行 php -v，输出中包含 Xdebug 的版本信息，则表示安装成功：

C:\Users\Administrator>php -v
PHP 7.2.7 (cli) (built: Jun 19 2018 23:13:48) ( NTS MSVC15 (Visual C++ 2017) x64 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologieswith Xdebug v2.7.0alpha1, Copyright (c) 2002-2018, by Derick Rethans

注意，[Xdebug] 在 Linux 需要区分大小写。

设置 Xdebug

Xdebug 是 C/S 结构，Client 是 PHP 中安装的 Xdebug，Server 是 IDE 中安装的插件。PHP 脚本运行时，Xdebug 可以向 IDE 报告运行状态，并将调试信息发送给 IDE。

Xdebug

Xdebug 有大量的配置参数可以设置，完整设置可以参考这里，常用设置如下：

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;远程调试相关设置
;用于验证服务器，只有 Xdebug 的服务器与客户端的 idekey 匹配时才会发送调试消息
xdebug.idekey="PhpStorm"
;开启远程调试
xdebug.remote_enable=on
;自动启动远程调试，对于不是 web 应用的 PHP 程序来说，必须开启
xdebug.remote_autostart=on
xdebug.remote_mode="req"
xdebug.remote_log="d://lnmp/log/phpxdebug.log"
xdebug.remote_handler="dbgp"
;远端 Xdebug 服务器的 IP 地址
xdebug.remote_host=localhost
;远端 Xdebug 服务器的端口，在 IDE 中设置
xdebug.remote_port=9001;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;trace 代码跟踪相关设置
;是否允许Xdebug跟踪函数调用，跟踪信息以文件形式存储，默认值为0。用于调试 auto_prepend_file 中的代码
xdebug.auto_trace = 1
;代码跟踪日志文件位置，默认值为/tmp。需要先新建这个目录，并设置读写权限
xdebug.trace_output_dir=d://lnmp/log/php
;函数调用跟踪信息输出文件命名规则，默认为 trace.%c
xdebug.trace_output_name=trace.%c.%p
;是否允许 Xdebug 跟踪函数参数，默认值为0
xdebug.collect_params = 4
xdebug.collect_includes = On
;是否允许 Xdebug 跟踪函数返回值，默认值为0
xdebug.collect_return = On
xdebug.show_mem_delta = On
;设置数组或者对象显示的最大层级，默认是3
xdebug.var_display_max_depth = 2;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;profile 性能探查相关设置
;打开性能分析器，默认值为0
xdebug.profiler_enable=1
;性能分析文件的存放位置，默认值为/tmp。需要先新建这个目录，并设置读写权限
xdebug.profiler_output_dir=d://lnmp/log/php
;性能分析文件的命名规则，默认值为cachegrind.out.%p
xdebug.profiler_output_name=profiler.%c.%p

配置 IDE（以 PhpStorm 为例）

PhpStorm 设置项参考手册

调试非 web 应用

PHP 中的 Xdebug 配置完成后，接下来需要在 IDE 中设置 Xdebug 服务器，通过监听端口来获取代码运行状态。

添加 PHP 解释器

设置的路径：打开 IDE 后，依次选择 File | Settings | Languages & Frameworks | PHP，选择 PHP 版本和脚本位置即可。

这里写图片描述

设置 Xdebug

设置的路径：打开 IDE 后，依次选择 File | Settings | Languages & Frameworks | PHP | Debug，可以看到 Debug 相关设置。最重要的是端口号，默认是 9000，但这会跟 PHP-FPM 冲突，所以这里改为 9001。同时，需要在 php.ini 配置文件中通过 xdebug.remote_port=9001 告诉 Xdebug 客户端，服务器监听的端口号是 9001。

当前设置页面的参考手册在这里。

Debug

调试 web 应用

Debugging PHP Web Applications with Run Debug Configurations

PhpStorm 中可以通过 Run | Edit Configuration 进入 Run/Debug Configuration 调试设置页面，在这里添加测试项目后，点击调试按钮后，IDE 会自动打开浏览器，输好网址并添加这个字符串 XDEBUG_SESSION_START=session_name。
这里写图片描述

设置 Xdebug 代理

字段	描述
IDE key	指定代理服务器的名称以标识 IDE 中的连接。这应该是当前活动的 `php.ini` 配置文件中 `xdebug.idekey` 设置的值。
Host	指定 Xdebug 代理服务器所在的主机。
Port	指定在代理调试会话期间 PhpStorm 将侦听的端口。

这里写图片描述

配置 debug 参数

配置浏览器

Xdebug 和 IDE 配置完成后，就可以调试非 web 应用了。对于需要在浏览器中调试的 web 应用，还需要在浏览器中安装插件，Chrome 直接安装 Xdebug Helper 就行了，其他浏览器可以参考这里。

插件安装好后，打开 PhpStorm 并监听 debug 连接（Run | Start Linstening for PHP Debug Connections，也就是调试工具栏中的小电话）。然后点击刚安装好的插件，选择 debugging、profiling 或 tracing 会话，在浏览器端初始化一个连接。

这里写图片描述