Debian如何进行PHP代码调试

今天这篇，我们来聊聊一个实战话题：怎么在Debian系统上给PHP代码做调试。这件事，说复杂也复杂，说简单也简单。关键是把工具链搭对，尤其是Xdebug这个核心组件。下面我们一步步走通整个流程。

要把这件事做好，得从最基础的准备说起。

前置准备

调试环境不是凭空来的。动工之前，先确认两件事：系统里到底有没有装PHP，对应的Web服务器（Apache、Nginx或者PHP-FPM）是不是在跑着。命令不复杂，php -v看一眼PHP版本，systemctl status apache2或systemctl status nginx确认一下服务器状态。这两步走完，心里就有底了。

安装Xdebug扩展

Xdebug这个名字，搞PHP开发的应该都不陌生。它堪称调试领域的“瑞士军刀”，断点、变量监控、函数跟踪，样样在行。安装过程其实是Debian系最舒服的部分——包管理器直接搞定。

1. 先更新一下软件包索引：sudo apt update
2. 接着安装Xdebug：sudo apt install php-xdebug。注意，系统会自动匹配你当前的PHP版本，比如你的环境是PHP 8.2，它会自动装好php8.2-xdebug，省心得很。
3. 装完验证一下：php -m | grep xdebug。如果屏幕上赫然出现xdebug三个字，那就算成了。

配置Xdebug

装好只是第一步，真正出活儿的地方在配置里。这里有几个细节容易踩坑，得仔细说。

首先，找到php.ini文件。别急着一通乱找，运行php --ini就能看到当前加载的配置文件路径。特别需要注意的是，运行环境不同，ini文件的位置也不同：

• 命令行环境下用：/etc/php/8.x/cli/php.ini
• Apache环境下用：/etc/php/8.x/apache2/php.ini
• PHP-FPM环境下用：/etc/php/8.x/fpm/php.ini

找到目标文件后，在末尾加上下面这段配置。关键参数我已经标了注释，方便你理解每行的作用：

[Xdebug]
zend_extension=xdebug.so
# 加载Xdebug扩展——不用写完整路径，系统能自己找到

xdebug.mode=debug
# 必选项，开启调试模式

xdebug.client_host=127.0.0.1
# 调试客户端的IP，本地开发就写127.0.0.1

xdebug.client_port=9003
# 调试端口，默认是9003，一定要跟IDE里设置的一致

xdebug.start_with_request=yes
# 是否自动启动调试。可选trigger、yes、off。建议直接yes，省得每次手动触发

xdebug.idekey=PHPSTORM
# IDE标识，PHPStorm或VSCode都能用。不是必须的，但推荐设置一下

⚠️ 注意：如果你还在用PHP 7.x，记得把php8.x-xdebug换成对应版本（比如php7.4-xdebug），ini文件的路径也要相应调整版本号。

配置写完了，记得重启Web服务器让配置生效：

• Apache用户：sudo systemctl restart apache2
• PHP-FPM + Nginx用户：sudo systemctl restart php8.x-fpm && sudo systemctl restart nginx

配置IDE（以Visual Studio Code为例）

服务器端配置好了，下一步就是告诉IDE怎么跟Xdebug联动。我们以VS Code为例说清楚每一步。

1. 安装PHP Debug扩展。打开VS Code，在扩展商店里搜索“PHP Debug”，作者是Felipe Ta voni，点安装就行。

2. 创建launch.json文件。点击左侧的“运行和调试”图标（就是那个小虫子），再点顶部的齿轮图标，选择“PHP”环境。VS Code会自动生成一个.vscode/launch.json文件。把它改成下面这样：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            // 注意！端口必须跟上面Xdebug配置里的client_port一致
            "pathMappings": {
                // pathMappings是关键——服务器上的项目路径要映射到本地工作区
                "/var/www/html": "${workspaceFolder}"
                // 左边是服务器上的路径，右边是本地项目的根目录
            },
            "stopOnEntry": false
            // 设为true的话，调试启动时会自动暂停在第一行，根据习惯设置就行
        }
    ]
}

这里稍微解释一下：pathMappings是绝大多数人踩坑的地方。简单说，你的代码在服务器上跑在/var/www/html，但在本地开发时在${workspaceFolder}（就是你用VS Code打开的那个文件夹）。如果不把这个映射关系告诉IDE，断点永远触发不了。

1. 验证配置。按下F5启动调试会话，VS Code会开始监听9003端口，等着Xdebug来连接。这一步成功的话，帷幕就拉开了。

开始调试

一切就绪，终于可以动手了。

1. 设置断点。在VS Code里打开你要调试的PHP文件，在需要暂停的行号左侧点一下鼠标，一个红色圆点就出现了——这就是断点。

2. 触发调试。有两种方法：

   • 浏览器方式：安装一个Xdebug Helper插件（Chrome和Firefox都有），点击插件图标开启调试模式，然后正常访问你的PHP页面（比如http://localhost/test.php）。代码执行到断点处就会自动暂停。
   • 命令行方式：直接curl http://localhost/test.php，或者在终端里运行脚本。如果你之前配置了xdebug.start_with_request=yes，那也会触发调试。

3. 调试操作。代码暂停后，VS Code顶部会弹出调试工具栏，几个常用功能记一下：

   • 单步跳过（F10）：执行当前行，但不进函数内部。
   • 单步进入（F11）：钻进函数内部，看看里面在干什么。
   • 继续（F5）：放行，继续跑到下一个断点。
   • 查看变量：左侧的“变量”面板会显示当前作用域里的所有变量值。“监视”面板还能自定义表达式，想查什么写上就行。

常见问题排查

调试环境不是一次就能跑通的，遇到问题别慌，常见的坑就那么几个。

1. 端口冲突：9003端口被别的程序占了？简单，把xdebug.client_port改成9004，IDE里也同步改一下就行。
2. 路径映射错误：这是出镜率最高的错误。记住，pathMappings里的服务器路径一定要跟真实路径一致，不能多一个斜杠，不能少一个字母。
3. Xdebug没有加载：检查php.ini里zend_extension=xdebug.so这一行有没有被注释掉。还可以跑一下php -m | grep xdebug看看它到底在不在。

补充调试方法（可选）

Xdebug是主力，但有时候也会用到些辅助手段。

1. 错误日志。在php.ini里开启错误日志，能帮你定位那些没被捕获的异常：

   display_errors = Off
   # 生产环境记得关掉浏览器显示
   log_errors = On
   # 开启日志记录
   error_log = /var/log/php_errors.log
   # 日志文件路径，提前确认这个目录是可写的
   

2. var_dump和print_r。这算是老办法了，但有时候反而最直接。在代码里插一句var_dump($variable)或者print_r($array, true)，一眼就能看到变量值。当然，生产环境记得删掉，或者用error_log()代替。