Docker Compose+Nginx+PHP环境下Xdebug监听失效问题求助

环境信息 #

• 系统：Linux Ubuntu
• 运行环境：Docker Compose
• Xdebug版本：v3.2.2
• IDE：VSCode
• 状态：执行phpinfo();显示Xdebug已正常启用，但VSCode监听时断点无响应

Docker Compose配置 #

version: '3.8'

services:
  app:
    container_name: app
    build:
      context: .
      dockerfile: .docker/php/Dockerfile
    volumes:
      - .:/var/www/html
      - .docker/php/conf.d/local.ini:/usr/local/etc/php/conf.d/local.ini
      - .docker/php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
      - .docker/php/conf.d/error_reporting.ini:/usr/local/etc/php/conf.d/error_reporting.ini
    extra_hosts:
      - "host.docker.internal:host-gateway"
    mem_limit: 1024m
    mem_reservation: 512M
    depends_on:
      - mysql
    networks:
      - app-network

  server:
    image: nginx:alpine
    container_name: server
    restart: unless-stopped
    tty: true
    ports:
      - "8000:80"
    dns:
      - 8.8.8.8
      - 4.4.4.4
    volumes:
      - .:/var/www/html
      - .docker/nginx/conf.d/:/etc/nginx/conf.d/
    networks:
      - app-network

PHP Dockerfile配置 #

FROM php:8.1.18-fpm
WORKDIR /var/www/html

COPY --chown=www-data:www-data . /var/www/html

RUN apt-get update -y && apt-get install -y curl zip unzip sendmail libpng-dev \
        libfreetype6-dev \
        libjpeg62-turbo-dev \
        libpng-dev \
        libonig-dev \
        default-mysql-client \
        net-tools \
        inetutils-ping \
        netcat \
        && docker-php-ext-configure gd --with-freetype=/usr/include/ --with-jpeg=/usr/include/ \
        && docker-php-ext-install gd

RUN apt-get install -y git
RUN apt-get install -y zip libzip-dev \
  && docker-php-ext-configure zip \
  && docker-php-ext-install zip \
  && docker-php-ext-install exif && docker-php-ext-enable exif

RUN docker-php-ext-install mysqli pdo pdo_mysql
RUN docker-php-ext-enable mysqli pdo pdo_mysql
RUN docker-php-ext-install pcntl

RUN pecl install -o -f xdebug \
    && docker-php-ext-enable xdebug

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

Nginx配置 #

server {
    listen 0.0.0.0:80;

    index index.php index.html;
    
    root /var/www/html/public;
    
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;

        # Enable CORS Preflighted requests
        if ($request_method = OPTIONS ) {
            add_header 'Access-Control-Allow-Origin'  '*';
            add_header 'Access-Control-Allow-Methods' '*';
            add_header 'Access-Control-Allow-Headers' '*';

            return 204;
        }

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        gzip_static on;
    }

    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
}

Xdebug配置文件（xdebug.ini） #

zend_extension=xdebug

[xdebug]
xdebug.mode = debug,develop
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.discover_client_host=1
xdebug.extended_info=1
xdebug.log=/tmp/xdebug.log
xdebug.idekey=VSCODE ; can also be phpstorm

;; ------------------------------------
;; Color var_dumps when in CLI
xdebug.cli_color=1

VSCode 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,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

phpinfo()截图 #

排查与解决步骤 #

1. 查看Xdebug日志定位问题
   进入容器查看Xdebug日志，直接获取连接失败的具体原因：

   docker exec app cat /tmp/xdebug.log
   

2. 修正Xdebug配置冲突
   配置中xdebug.start_with_request=yes与xdebug.discover_client_host=1同时存在可能导致连接目标混乱，建议注释掉自动发现主机的配置：

   xdebug.start_with_request=yes
   ; xdebug.discover_client_host=1
   

3. 开放主机端口
   确保Ubuntu主机的9003端口未被防火墙拦截：

   sudo ufw allow 9003/tcp
   

4. 验证路径映射准确性
   确认VSCode的路径映射与实际项目路径一致，可临时替换为绝对路径测试：

   "pathMappings": {
       "/var/www/html": "/home/你的用户名/你的项目目录"
   }
   

5. 重启服务与IDE
   修改配置后重启Docker容器与VSCode，确保配置生效：

   docker-compose down && docker-compose up -d --build
   

6. 检查端口占用状态
   确认9003端口未被其他程序占用：

   lsof -i :9003
   

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