PhpStorm IDE下使用Xdebug调试Docker容器内CLI PHP脚本失败问题咨询

核心原因 #

• 配置混用Xdebug2和Xdebug3的废弃参数，导致CLI场景下适配异常
• CLI模式无HTTP请求上下文，依赖请求IP的自动发现配置（xdebug.discover_client_host、xdebug.remote_connect_back）完全失效，无法定位宿主机IDE地址
• xdebug.start_with_request=trigger默认需要触发参数，CLI执行时无默认触发条件，不会启动调试

修复步骤 #

1. 修正docker-php-ext-xdebug.ini配置 #

清理废弃参数，替换为Xdebug3标准配置：

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.output_dir = "/tmp"

注：如果不需要每次执行CLI都自动启动调试，可将xdebug.start_with_request保留为trigger，执行脚本时手动传入触发环境变量即可
注：Linux系统下运行Docker需要在启动容器时添加--add-host=host.docker.internal:host-gateway参数，保证容器内可正常解析到宿主机IP

2. 按需使用触发环境变量 #

如果保留trigger配置，执行CLI脚本时添加对应的环境变量即可触发调试：

# 容器内直接执行
XDEBUG_SESSION=PHPSTORM php 脚本路径.php

# 宿主机直接执行容器内CLI脚本
docker exec -e XDEBUG_SESSION=PHPSTORM 容器名称 php 脚本路径.php

3. 验证配置 #

执行以下命令确认CLI模式下Xdebug配置加载正常：

php -i | grep xdebug

确认输出中的xdebug.client_host、xdebug.client_port、xdebug.idekey和配置值一致即可。

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