Debian怎样进行PHP代码调试

说到Debian下的PHP代码调试，Xdebug几乎是绕不开的一个工具。它支持断点调试、变量监控、函数跟踪，算是目前最主流的方案。下面就把整个配置和上手过程拆开来讲，每一步都尽量说清楚，避免掉坑。

一、准备工作：安装Xdebug扩展

安装本身不复杂，两条命令就能搞定：

1. 先更新软件包列表：sudo apt update
2. 然后安装Xdebug：sudo apt install php-xdebug。注意，如果你用的是PHP 8.x，需要把包名换成对应版本，比如php8.1-xdebug。

二、配置Xdebug：修改php.ini文件

Xdebug的配置取决于你的PHP运行环境——CLI、Apache、Nginx/PHP-FPM，对应的php.ini路径都不一样：

• Apache（模块模式）：/etc/php/{version}/apache2/php.ini
• Nginx/PHP-FPM：/etc/php/{version}/fpm/php.ini
• 命令行（CLI）：/etc/php/{version}/cli/php.ini

找到对应的文件后，在末尾追加以下配置。每行的作用已经写在注释里：

[Xdebug]
; 启用Xdebug扩展（路径通常自动识别，无需手动指定）
zend_extension=xdebug.so
; 设置调试模式为'debug'（必需）
xdebug.mode=debug
; 指定IDE监听的主机地址（默认本地）
xdebug.client_host=127.0.0.1
; 指定IDE监听的端口（默认9003，需与IDE一致）
xdebug.client_port=9003
; 自动启动调试会话（可选：'yes'表示所有请求都触发，'trigger'表示通过Cookie/GET参数触发）
xdebug.start_with_request=yes
; 可选：设置IDE标识（如PHPSTORM、VSCode），用于区分不同工具
xdebug.idekey=PHPSTORM

改完记得保存文件。

三、重启Web服务器：使配置生效

配置改完，服务器必须重启才能加载新参数：

• Apache：sudo systemctl restart apache2
• Nginx+PHP-FPM：sudo systemctl restart php{version}-fpm && sudo systemctl restart nginx（把{version}换成实际版本，比如8.1）

四、配置IDE：建立与Xdebug的连接

1. Visual Studio Code（推荐新手）

• 在扩展商店搜索“PHP Debug”并安装。
• 点击左侧“运行”图标 → “创建launch.json文件” → 选择“PHP Debug”，然后修改配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
                // 将服务器项目路径映射到本地工作区
            }
        }
    ]
}

• 点击顶部“开始调试”按钮（绿色三角形），VS Code就会进入监听状态。

2. PhpStorm（专业级工具）

• 打开设置：File → Settings → Languages & Frameworks → PHP → Servers，点击“+”添加服务器：
  • 名称随意，比如Local
  • 主机：localhost
  • 端口：80（或Nginx的443端口）
  • 勾选“Use path mappings”，把服务器路径（比如/var/www/html）映射到本地项目路径。
• 然后在Settings → PHP → Debug里确保“Xdebug”已启用，端口设为9003。

五、开始调试：设置断点与执行

1. 设置断点：在代码行号左侧点击，出现红色圆点就行。比如在$result = $db->query($sql);这一行设一个。
2. 触发调试：
   • 如果xdebug.start_with_request=yes，直接访问页面（比如http://localhost/index.php）就能触发。
   • 如果设成了trigger，那就需要浏览器里装个Xdebug Helper插件（Chrome/Firefox都有），点击插件图标开启调试模式后再访问页面。
3. 调试操作：代码执行到断点时，IDE会暂停，并显示：
   • 变量值（悬停或看“变量”面板）
   • 调用栈（“调用堆栈”面板）
   • 当前行的代码高亮
   可以用“继续”“单步跳过”“单步进入”这些按钮控制执行流程。

六、辅助调试技巧（可选）

除了用Xdebug，还有一些快速排查问题的方法：

• 错误日志：在代码里加上ini_set('display_errors', 1); ini_set('log_errors', 1); ini_set('error_log', '/var/log/php_errors.log');，把错误输出到指定文件。
• var_dump/print_r：简单粗暴，直接打印变量值，适合快速验证。
• 日志记录：用error_log("Debug: ".$variable);把关键信息写入日志，不会影响页面显示。

这样一套流程下来，Debian上的PHP调试环境就搭好了。VS Code适合轻量级调试，PhpStorm适合大型项目，选哪个看习惯就行。辅助技巧在特定场景下能省不少时间，可以根据实际需要灵活使用。