Docker环境下VSCode调试Yii 1.1失败：断点未触发求助

问题描述 #

在Docker运行的Yii 1.1应用中，VSCode配置Xdebug后断点完全未触发，已尝试StackOverflow及其他技术站点的解决方案仍无法解决。

使用的配置文件 #

docker-compose.yml #

version: '3'
services:
  web:
    container_name: php72
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:80"
    volumes:
      - ./:/var/www/html
      - ./xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    networks:
      - app-network

  mysql:
    image: mysql:8.0.31-oracle
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: '123456'
      MYSQL_USER: 'admin'
      MYSQL_PASSWORD: '123456'
      MYSQL_DATABASE: 'test_db'
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - 3306:3306
    networks:
      - app-network

networks:
  app-network:

volumes:
  db_data:

Dockerfile #

FROM php:7.2-apache

ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions gd xdebug pdo pdo_mysql pdo_pgsql mongodb mbstring zip


EXPOSE 80

xdebug.ini #

zend_extension=xdebug

[xdebug]
xdebug.mode=debug
xdebug.discover_client_host=1
xdebug.idekey=VSCODE
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.remote_host="host.docker.internal"

launch.json #

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        },
        {
            "name": "Launch Built-in web server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:8001"
            ],
            "program": "",
            "cwd": "${workspaceRoot}/../../",
            "port": 9003,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

项目结构与调试现状 #

项目结构 #

调试访问与结果 #

通过浏览器访问应用地址为localhost:8000，开启VSCode调试后状态如下：

排查与修复建议 #

• 修正Xdebug版本兼容性：PHP7.2仅支持Xdebug 2.x版本，Xdebug3要求PHP7.4及以上。当前Dockerfile未指定版本，可能安装了不兼容的Xdebug3。修改Dockerfile指定安装Xdebug2.9.8：

  RUN chmod +x /usr/local/bin/install-php-extensions && \
      install-php-extensions gd xdebug-2.9.8 pdo pdo_mysql pdo_pgsql mongodb mbstring zip
  

• 调整Xdebug配置文件：
  如果使用Xdebug2，xdebug.ini需改为：

  zend_extension=xdebug
  xdebug.remote_enable=1
  xdebug.remote_autostart=1
  xdebug.remote_connect_back=0
  xdebug.remote_host=host.docker.internal
  xdebug.remote_port=9003
  xdebug.idekey=VSCODE
  

  如果坚持使用Xdebug3（需确认PHP版本兼容），则移除旧参数xdebug.remote_host，并关闭自动发现主机：

  zend_extension=xdebug
  xdebug.mode=debug
  xdebug.discover_client_host=0
  xdebug.idekey=VSCODE
  xdebug.start_with_request=yes
  xdebug.client_port=9003
  xdebug.client_host=host.docker.internal
  

• 验证容器内Xdebug配置：
  进入容器执行命令：

  docker exec -it php72 bash
  php -v # 查看是否包含Xdebug版本信息
  php -i | grep xdebug # 检查配置参数是否正确加载
  

• 完善VSCode调试路径映射：
  在Listen for Xdebug配置中添加路径映射，确保本地工作区与容器内路径对应：

  {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
          "/var/www/html": "${workspaceRoot}"
      }
  }
  

• 检查网络连通性：
  在容器内执行ping host.docker.internal，确认能连通主机；同时检查本地9003端口是否被占用。

• 手动触发Xdebug会话：
  在浏览器访问URL时添加参数?XDEBUG_SESSION_START=VSCODE，或安装浏览器Xdebug插件并设置IDEKEY为VSCODE。

内容的提问来源于stack exchange，提问作者Ravi Mukti