Docker容器Xdebug连接VS Code报Cannot assign requested address问题求助

数据老陈

2026-10-4

核心问题排查及修复步骤

1. 修正Xdebug配置（核心错误：混用Xdebug2和Xdebug3参数）

你当前xdebug.ini中混用了两个版本的配置参数，Xdebug3不识别xdebug.remote_host、xdebug.remote_connect_back这些旧版本参数，导致你配置的host.docker.internal未生效，最终xdebug_info()输出的client_host使用了默认值localhost。

替换为适配Xdebug3的完整配置：

zend_extension=xdebug.so

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.discover_client_host=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.log=/tmp/xdebug-local.log
xdebug.force_error_reporting=1

2. 修正Docker Compose配置，添加宿主机映射

host.docker.internal默认不会在Linux环境的Docker容器中自动注入，需要手动配置宿主机网关映射。在docker-compose.yml的wordpress服务中添加extra_hosts配置：

version: "3"

services:
  wordpress:
    build: .
    # 新增如下配置
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      VIRTUAL_HOST: "myproject.test"
      WORDPRESS_DB_HOST: "mysql"
      WORDPRESS_DB_NAME: "wordpress"
      WORDPRESS_DB_PASSWORD: ""
      WORDPRESS_DB_USER: "root"
    depends_on:
      - "mysql"
    networks:
      - "front"
      - "back"
    volumes:
      - "wp:/var/www/html:rw"
      - "./my-wp-plugin:/var/www/html/wp-content/plugins/my-wp-plugin:ro"

3. 冗余配置清理&前置检查

Dockerfile中的ufw allow 9003配置可以删除：Xdebug是容器主动连接宿主机的9003端口，不需要容器内部开放端口，容器内ufw默认也不会生效。
每次调整配置后需要重建容器：执行docker-compose up -d --build让配置生效。
调试启动顺序：先在VSCode中按F5启动Xdebug监听器，再访问站点触发调试，避免出现连接拒绝报错。
宿主机端口放行：确保宿主机防火墙未拦截9003端口，Linux环境可临时执行sudo ufw allow 9003测试。

4. 验证连通性

容器启动完成后进入容器内部，执行telnet host.docker.internal 9003，如果显示连通则配置生效，再次访问站点即可触发VSCode断点。

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