WSL环境下Docker自动占用Xdebug 9003端口的问题求助

问题详情 #

Xdebug已在phpinfo()中确认正常安装，但启动VS Code调试时，Docker会自动占用配置的9003端口，导致调试无法正常进行。通过PowerShell命令 netstat -ano | findstr :9003 验证，9003端口确实被Docker进程占用。

当前配置 #

Xdebug初始配置（xdebug.ini） #

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=docker
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

Docker Compose配置 #

version: "3"
services:
  web:
    build:
      context: ./docker
      dockerfile: Dockerfile
    ports:
      - "8000:80"
      - "9003:9003"
    volumes:
      - .:/app
      - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    environment:
      - XDEBUG_MODE=debug
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: database
    ports:
      - "3306:3306"

VS Code launch.json配置 #

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

Xdebug验证结果 #

root@container:/app# php -m | grep xdebug
xdebug

已尝试的无效方法 #

• 将xdebug.client_host替换为xdebug.discover_client_host=1，但Docker容器内的localhost指向容器自身，导致Xdebug无法连接宿主机器
• 在docker-compose.yml中创建自定义网桥
• 确认php.ini未覆盖xdebug.ini的配置项

解决方案 #

核心修复：移除Docker端口映射 #

Xdebug的工作逻辑是容器内的PHP进程主动发起连接到宿主机器上的VS Code调试监听端口，而非宿主机器连接容器的9003端口。因此不需要在Docker Compose中映射9003端口，这正是导致端口被Docker占用的原因。

修改docker-compose.yml的web服务端口配置，删除- "9003:9003"这一行：

ports:
  - "8000:80"

额外注意事项 #

1. 确保host.docker.internal在WSL环境下有效：该域名默认会解析到宿主机器的IP，若出现解析失败，可手动指定宿主的局域网IP（比如通过ipconfig在Windows下获取）或WSL的IP（执行hostname -I获取），替换xdebug.client_host的值
2. 调试流程：先启动VS Code的"Listen for Xdebug"监听，再触发PHP请求（如访问网页、执行CLI脚本），Xdebug会主动连接VS Code的9003端口
3. 若需更换端口：如果9003端口被其他进程占用，可修改xdebug.ini的xdebug.client_port为其他值（如9004），同时同步修改VS Code launch.json中的port配置即可

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