Win10(WSL2)环境下如何将VSCode连接至Docker容器内的Xdebug 3？

我在Windows 10 WSL2环境下用Docker Compose搭建Nginx+PHP-FPM+MariaDB+Adminer的开发环境时，遇到了Xdebug无法触发调试的问题，折腾一番后终于解决，分享下过程和方案：

问题场景 #

环境里的所有组件都正常运行，本地端口连通性测试也没问题：

PS D:\Projects\php-docker\dev> tnc host.docker.internal -p 9003
ComputerName     : host.docker.internal
RemoteAddress    : 192.168.0.5
RemotePort       : 9003
InterfaceAlias   : Ethernet
SourceAddress    : 192.168.0.5
TcpTestSucceeded : True

进入PHP容器也确认Xdebug已经正确安装：

kds@matrix:/mnt/d/Projects/php-docker/dev$ docker exec -it dev_php_1 bash
root@2aa7df39190d:/var/www/html# php -v
PHP 8.0.6 (cli) (built: May  7 2021 20:37:21) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.6, Copyright (c) Zend Technologies
    with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethans

但VS Code的Xdebug监听始终无法触发断点。

初始配置（存在问题的版本） #

docker-compose.yml #

version: '3'
services:
  web:
    image: nginx
    restart: always
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/nginx.conf
      - ./app:/www/app
  php:
    build:
      context: .
      dockerfile: PHP_Dockerfile
    volumes:
      - ./app:/www/app
      - ./logs/xdebug:/logs/xdebug
    environment:
      XDEBUG_CONFIG: "mode=debug start_with_request=yes client_host=host.docker.internal client_port=9003"
  mysql:
    image: mariadb
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: 'secret'
      MYSQL_USER: 'db_user'
      MYSQL_PASSWORD: 'secret'
      MYSQL_DATABASE: 'test'
    volumes:
      - mysqldata:/var/lib/mysql
    ports:
      - 3306:3306
  adminer:
    image: adminer:latest
    restart: always
    environment:
      ADMINER_DESIGN: ng9
      ADMINER_DEFAULT_SERVER: mysql
    ports:
      - 8080:8080
volumes:
  mysqldata: {}

PHP_Dockerfile #

FROM php:fpm
RUN docker-php-ext-install pdo pdo_mysql \
    && pecl install xdebug \
    && docker-php-ext-enable xdebug

VS Code launch.json #

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "stopOnEntry": true,
      "log": true,
      "pathMappings": {
        "/www/app": "${workspaceFolder}/app"
      },
    },
  ]
}

解决方法 #

通过单独添加Xdebug配置文件并调整Docker Compose设置，问题得以解决：

1. 创建独立的xdebug.ini配置文件 #

[XDebug]
zend_extension=xdebug.so
xdebug.mode = debug
xdebug.start_with_request=yes
# 如果是Linux系统，把host.docker.internal换成你的电脑IP地址
xdebug.client_host=host.docker.internal

2. 修改docker-compose.yml配置 #

将PHP服务原有的XDEBUG_CONFIG环境变量替换为挂载xdebug.ini的配置，同时添加PHP_IDE_CONFIG环境变量用于匹配IDE的服务器名称：

version: '3'
services:
  web:
    image: nginx
    restart: always
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/nginx.conf
      - ./app:/www/app
  php:
    build:
      context: .
      dockerfile: PHP_Dockerfile
    volumes:
      - ./app:/www/app
      - ./xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    environment:
      PHP_IDE_CONFIG: "serverName=docker-test"
  mysql:
    image: mariadb
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: 'secret'
      MYSQL_USER: 'db_user'
      MYSQL_PASSWORD: 'secret'
      MYSQL_DATABASE: 'test'
    volumes:
      - mysqldata:/var/lib/mysql
    ports:
      - 3306:3306
  adminer:
    image: adminer:latest
    restart: always
    environment:
      ADMINER_DESIGN: ng9
      ADMINER_DEFAULT_SERVER: mysql
    ports:
      - 8080:8080
volumes:
  mysqldata: {}

调整完成后，Xdebug就能正常和VS Code的调试监听建立连接，断点也可以正常触发了。

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