Debian如何进行PHP代码调试

Debian系统PHP代码调试指南（以Xdebug为核心）

一、前置准备

调试前需确认系统已安装PHP及对应Web服务器（Apache/Nginx/PHP-FPM）。可通过php -v查看PHP版本，systemctl status apache2/nginx确认服务器状态。

二、安装Xdebug扩展

Xdebug是PHP专业调试工具，支持断点、变量监控、函数跟踪等功能。

更新软件包索引：sudo apt update
安装Xdebug：sudo apt install php-xdebug（自动适配当前PHP版本，如php8.2-xdebug）
验证安装：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配置：
在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为例）

安装PHP Debug扩展：
打开VS Code，点击左侧扩展图标，搜索“PHP Debug”并安装（作者：Felipe Tavoni）。

创建launch.json文件：
点击左侧调试图标→点击顶部齿轮图标→选择“PHP”，自动生成.vscode/launch.json文件。修改为以下内容（适配Xdebug配置）：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,                  // 必须与Xdebug的client_port一致
            "pathMappings": {              // 本地项目路径与服务器路径映射（关键！）
                "/var/www/html": "${workspaceFolder}"  // 示例：服务器项目路径→本地工作区
            },
            "stopOnEntry": false           // 可选：启动时是否暂停
        }
    ]
}

验证IDE配置：
按F5启动调试会话，VS Code会监听9003端口，等待Xdebug连接。

五、开始调试

设置断点：
在VS Code中打开PHP文件，在需要调试的行号左侧点击（红色圆点），设置断点。
触发调试：
- 浏览器方式：安装Xdebug Helper插件（Chrome/Firefox），点击插件图标开启调试模式，访问PHP页面（如http://localhost/test.php），代码执行到断点时暂停。
- 命令行方式：使用curl http://localhost/test.php或直接在终端运行脚本，若配置了xdebug.start_with_request=yes，也会触发调试。
调试操作：
暂停后，可通过VS Code顶部调试栏进行：
- 单步跳过（F10）：执行当前行，不进入函数内部。
- 单步进入（F11）：进入函数内部调试。
- 继续（F5）：继续执行到下一个断点。
- 查看变量：左侧“变量”面板可查看当前作用域的变量值；“监视”面板可添加自定义表达式。

六、常见问题排查

端口冲突：若9003端口被占用，修改xdebug.client_port为其他端口（如9004），并同步更新IDE配置。
路径映射错误：确保pathMappings中的服务器路径与本地项目路径一致，否则无法正确显示变量和代码。
Xdebug未加载：检查php.ini中zend_extension路径是否正确（Debian下通常为xdebug.so，无需完整路径），可通过php -m | grep xdebug验证。

七、补充调试方法（可选）

错误日志：
在php.ini中开启错误日志，便于定位未捕获的异常：

display_errors = Off              # 生产环境关闭浏览器显示
log_errors = On                   # 开启日志记录
error_log = /var/log/php_errors.log  # 日志文件路径（需确保目录可写）

var_dump/print_r：
在代码中插入var_dump($variable)或print_r($array, true)，快速查看变量值（生产环境需移除或用error_log()替代）。