Docker环境下跨Nginx代理的Xdebug无法连接调试客户端问题求助

核心问题是你搞错了Xdebug的连接方向：Xdebug是从容器内部主动发起连接到宿主机器的IDE服务，不是接收外部入站请求，所以Nginx完全不需要处理9005端口的流量，你之前的9005端口相关配置全部是无效的。

步骤1：删除无效的端口配置 #

• 删掉backend服务expose配置中的9005条目
• 删掉nginx-proxy服务expose配置中的9005条目

步骤2：修正Xdebug配置 #

原有Xdebug配置缺少端口指定，且未适配Docker环境的调试规则，修改Dockerfile中Xdebug的配置段如下：

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode = debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host = host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_port = 9005" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.start_with_request = yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.discover_client_host = 0" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

步骤3：修正Docker Compose配置 #

首先修复原有配置中多余的空格问题（环境变量、卷路径中的等号、路径两侧不能有空格），然后给backend服务新增extra_hosts配置解决Linux环境下host.docker.internal无法解析的问题，修改后配置如下：

backend:
  build: backend
  container_name: backend
  volumes:
    # 复用本地composer缓存
    - ~/.composer-docker/cache:/root/.composer/cache: delegated
    # 挂载本地源码用于开发
    - ./:/app
  expose:
    - 80
  depends_on:
    - console
  environment:
    - VIRTUAL_HOST=backend.cliq.com
  # 新增host.docker.internal解析配置，Docker 20.10+版本均支持
  extra_hosts:
    - "host.docker.internal:host-gateway"

nginx-proxy:
  build: docker/nginx-proxy
  container_name: nginx-proxy
  ports:
    - "80:80"
  volumes:
    - /var/run/docker.sock:/tmp/docker.sock:ro

步骤4：本地IDE校验 #

• 打开IDE的Xdebug监听功能，监听端口设置为9005
• 配置IDE的路径映射：将容器内的/app目录映射到本地项目的根目录
• 关闭本地防火墙对9005端口的入站限制

验证方法 #

进入backend容器执行以下命令验证网络连通性：

# 验证域名解析
ping host.docker.internal
# 验证端口连通性，返回Connected字样说明网络正常
nc -zv host.docker.internal 9005

如果nc命令返回连通成功，重新触发请求即可正常进入调试。

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