使用Xdebug v3在Docker+VS Code中调试PHP代码失败求助

核心问题分析 #

你遇到的现象（Xdebug连接提示消失但VSCode状态栏不变橙、断点无效），大概率是配置冲突、路径映射错误或YAML格式问题导致的，以下是针对性的排查和修复方案：

1. 修复Xdebug配置冲突与冗余 #

Xdebug 3已弃用remote_*前缀的参数，你当前的php.ini中同时存在新旧参数，且docker-compose.yml的环境变量也重复设置了Xdebug参数，容易引发冲突：

修改后的php.ini（清理冗余参数） #

[xdebug]
zend_extension=xdebug
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=host.docker.internal

2. 修正Docker Compose的XDEBUG_CONFIG格式 #

你的docker-compose.yml中XDEBUG_CONFIG采用换行写法，YAML会将其解析为数组，而Xdebug需要的是空格分隔的键值对字符串，这会导致参数不生效：

修改后的docker-compose.yml环境变量部分 #

environment:
  MYSQL_DB_CONNECTION: test
  MYSQL_DB_NAME: test
  MYSQL_USER: test
  MYSQL_PASSWORD: test
  SITE_URL: http://localhost
  XDEBUG_MODE: develop,debug
  XDEBUG_CONFIG: "client_host=host.docker.internal start_with_request=yes client_port=9003"

3. 修正路径映射（断点无效的关键） #

你的launch.json中路径映射错误：容器内/var/www/html挂载的是本地./app目录，但${workspaceFolder}指向的是VSCode打开的项目根目录（包含docker-compose.yml的目录），因此映射关系应该是容器路径对应本地${workspaceFolder}/app：

修改后的launch.json #

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen on Docker for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}/app"
            },
            "hostname": "0.0.0.0",
            "log": true,
            "logPath": "${workspaceFolder}/xdebug.log"
        }
    ]
}

添加log参数可以生成调试日志，方便后续排查连接问题。

4. 验证Xdebug实际配置 #

取消xdebug_info.php中xdebug_info()的注释，访问该页面查看Xdebug的实际运行参数：

<?php
xdebug_info();
// phpinfo();

重点检查：

• Xdebug Mode是否为develop,debug
• Start With Request是否为Yes
• Client Host是否为host.docker.internal
• Client Port是否为9003

5. 生效配置并测试 #

1. 重启Docker容器：docker-compose down && docker-compose up -d --build
2. 在VSCode中启动调试监听（点击左侧调试图标，选择Listen on Docker for Xdebug并启动）
3. 在本地app目录的PHP文件中设置断点，访问对应页面，查看断点是否触发

内容的提问来源于stack exchange，提问作者Rafael Rodrigues