WSL下Laradock+PHP7.2为PhpStorm/VSCode配置Xdebug联调Laravel失败

在WSL环境下为基于Laradock搭建的Laravel开发项目配置Xdebug时遇到难以解决的问题：先后尝试对接PhpStorm、VSCode两类IDE的调试能力，也尝试使用Xdebug 3，按照Xdebug 3的全新配置语法在php-fpm与workspace对应的xdebug.ini中写入了适配的配置项，但始终无法正常触发调试链路。曾尝试修改xdebug.ini的各类参数组合均未成功，也不确定是否需要在WSL内部补充其他配置项。

以下为使用的全部配置内容：

• php-fpm/xdebug.ini配置：

xdebug.remote_host="host.docker.internal"
xdebug.remote_connect_back=0
xdebug.remote_port=9000
xdebug.idekey=PHPSTORM

xdebug.remote_autostart=1
xdebug.remote_enable=1
xdebug.cli_color=1
xdebug.profiler_enable=0
xdebug.profiler_output_dir="~/xdebug/phpstorm/tmp/profiling"

xdebug.remote_handler=dbgp
xdebug.remote_mode=req

xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
xdebug.var_display_max_depth=-1

• php-workspace/xdebug.ini配置：

xdebug.remote_host="host.docker.internal"
xdebug.remote_connect_back=0
xdebug.remote_port=9000
xdebug.idekey=PHPSTORM

xdebug.remote_autostart=1
xdebug.remote_enable=1
xdebug.cli_color=1
xdebug.profiler_enable=0
xdebug.profiler_output_dir="~/xdebug/phpstorm/tmp/profiling"

xdebug.remote_handler=dbgp
xdebug.remote_mode=req

xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
xdebug.var_display_max_depth=-1

• Laradock目录下.env相关配置：

...
WORKSPACE_INSTALL_XDEBUG=true
...
PHP_FPM_INSTALL_XDEBUG=true
...
# 请勿同时启用blackfire与xDebug
INSTALL_BLACKFIRE=false

• Laradock/PHP-FPM/Dockerfile中Xdebug相关构建配置：

###########################################################################
# xDebug:
###########################################################################

ARG INSTALL_XDEBUG=false

RUN if [ ${INSTALL_XDEBUG} = true ]; then \
  # 安装xdebug扩展
  if [ $(php -r "echo PHP_MAJOR_VERSION;") = "5" ]; then \
    pecl install xdebug-2.5.5; \
  else \
    if [ $(php -r "echo PHP_MINOR_VERSION;") = "0" ]; then \
      pecl install xdebug-2.9.0; \
    else \
      pecl install xdebug-2.9.8; \
    fi \
  fi && \
  docker-php-ext-enable xdebug \
;fi

# 复制xdebug远程调试配置
COPY ./xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

RUN sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /usr/local/etc/php/conf.d/xdebug.ini && \
    sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /usr/local/etc/php/conf.d/xdebug.ini && \
    sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /usr/local/etc/php/conf.d/xdebug.ini

• Laradock/WORKSPACE/Dockerfile中Xdebug相关构建配置：

###########################################################################
# xDebug:
###########################################################################

USER root

ARG INSTALL_XDEBUG=false

RUN if [ ${INSTALL_XDEBUG} = true ]; then \
  # 安装xdebug扩展
  if [ $(php -r "echo PHP_MAJOR_VERSION;") = "5" ]; then \
    pecl install xdebug-2.5.5; \
  else \
    if [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && [ $(php -r "echo PHP_MINOR_VERSION;") = "0" ]; then \
      pecl install xdebug-2.9.0; \
    else \
      if [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && [ $(php -r "echo PHP_MINOR_VERSION;") = "1" ]; then \
        pecl install xdebug-2.9.8; \
      else \
        if [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ]; then \
          pecl install xdebug-2.9.8; \
        else \
          # pecl install xdebug; \
          echo "需使用xDebug 3，当前环境不支持"; \
        fi \
      fi \
    fi \
  fi && \
  echo "zend_extension=xdebug.so" >> /etc/php/${LARADOCK_PHP_VERSION}/cli/conf.d/20-xdebug.ini \
;fi

# 复制xdebug远程调试配置
COPY ./xdebug.ini /etc/php/${LARADOCK_PHP_VERSION}/cli/conf.d/xdebug.ini

RUN sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /etc/php/${LARADOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
    sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /etc/php/${LARADOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
    sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /etc/php/${LARADOCK_PHP_VERSION}/cli/conf.d/xdebug.ini

• laradock/docker-compose.yml中Xdebug相关构建传参配置：

### Workspace 工具服务配置 ##################################
    workspace:
      build:
        context: ./workspace
        args:
           ...
          - INSTALL_XDEBUG=${WORKSPACE_INSTALL_XDEBUG}
          ...
### PHP-FPM ##############################################
    php-fpm:
      build:
        context: ./php-fpm
        args:
          ...
          - INSTALL_XDEBUG=${PHP_FPM_INSTALL_XDEBUG}
          ...

目前已完成PhpStorm的调试服务配置、Windows侧的网络放行设置，可提供对应配置截图及phpinfo输出结果供参考，需要协助定位调试链路无法打通的根本原因。

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