Docker开发环境下xDebug配合PHPStorm无法调试问题求助

修复步骤 #

1. 替换Xdebug配置为3.x版本语法 #

bitnami/php-fpm:7.4镜像内置Xdebug为3.x版本，你当前使用的Xdebug 2.x配置完全不生效，将php.ini中[Xdebug]段替换为如下内容：

[Xdebug]
zend_extension="/opt/bitnami/php/lib/php/extensions/xdebug.so"
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.log="/tmp/xdebug.log"

Xdebug 3.x将原有remote_host调整为client_host、remote_port调整为client_port，默认端口从9000变更为9003，废弃了remote_handler配置项无需保留。

2. 补充Docker Compose配置 #

在docker-compose.yml的php服务配置块中新增extra_hosts参数，确保Linux环境下容器可以正常访问宿主机器：

php:
  container_name: www-xtrose-php
  image: 'bitnami/php-fpm:7.4'
  extra_hosts:
    - "host.docker.internal:host-gateway"
  volumes:
    - './www:/app:delegated'
    - './docker/php/php.ini:/opt/bitnami/php/etc/conf.d/php.ini:ro'

Windows/macOS环境可省略该配置，添加后也不会影响兼容性。

3. 调整PHPStorm配置 #

• 打开「设置→PHP→调试」，将Xdebug调试端口修改为9003，和php.ini配置保持一致
• 进入「设置→PHP→服务器」，新增站点配置，端口填实际访问的端口（10011/10012），勾选「使用路径映射」，将本地项目的www目录映射到容器内的/app目录
• 确认IDE右上角Xdebug监听开关（电话图标）处于开启状态

4. 验证生效 #

重启所有Docker容器，新建phpinfo文件确认Xdebug配置加载正确，之后即可正常命中断点。

内容的提问来源于stack exchange，提问作者xtrose Media Studio