Ubuntu 22.04下VSCode调试PHP8.1的Xdebug配置求助

1. 安装Xdebug #

直接用Ubuntu官方源安装对应版本的Xdebug：

• 终端执行命令：sudo apt install php8.1-xdebug
• 验证安装结果：运行php -v，输出中若出现with Xdebug v3.x.x字样，说明安装成功

2. 配置Xdebug核心参数 #

找到Xdebug的配置文件，CLI模式下路径通常是/etc/php/8.1/cli/conf.d/20-xdebug.ini，网页调试用FPM的话路径是/etc/php/8.1/fpm/conf.d/20-xdebug.ini。编辑文件添加或修改以下内容：

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.log = /var/log/xdebug.log

• 关键参数说明：
  • xdebug.mode = debug：开启调试模式，是Xdebug 3的新写法，替代旧版的xdebug.remote_enable
  • xdebug.start_with_request = yes：每次请求自动触发调试，无需手动添加GET参数
  • xdebug.client_port = 9003：Xdebug 3默认端口，与VS Code调试插件默认端口一致
• 保存配置后，若使用FPM则重启服务：sudo systemctl restart php8.1-fpm

3. 配置VS Code调试环境 #

• 在VS Code插件商店搜索并安装PHP Debug插件（作者为Felix Becker）
• 打开你的PHP项目，创建.vscode/launch.json文件，粘贴以下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch current script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

4. 测试调试流程 #

• 新建或打开一个PHP文件，比如test.php，写入测试代码：

<?php
$message = "Debug test success!";
echo $message;
// 点击行号左侧灰色区域设置断点，会出现红色圆点
var_dump($message);
?>

• 打开VS Code左侧的「运行和调试」面板（快捷键Ctrl+Shift+D），选择「Listen for Xdebug」，点击绿色启动按钮
• 终端执行php test.php（CLI调试），或用浏览器访问该文件（网页调试）
• 此时VS Code会自动停在断点处，可查看变量、单步执行（F10/F11）、继续运行（F5）

常见问题排查 #

• 断点未触发：查看Xdebug日志/var/log/xdebug.log，里面会记录连接失败的具体原因（如端口被占用、配置参数错误）
• 端口占用检查：执行sudo lsof -i :9003，若有其他进程占用，可杀掉进程或修改Xdebug与VS Code的端口
• 配置生效验证：运行php -i | grep xdebug，检查输出中的参数是否与你配置的一致

内容的提问来源于stack exchange，提问作者Harsh Patel