Laradock环境下php-fpm/xdebug status命令失效，请求协助手动开启Xdebug

问题背景 #

• 环境：Mac系统，Docker、Docker Compose版本见附图；Laradock已开启workspace和php-fpm的Xdebug，使用PHP 7.4 + Xdebug 3.2.6
• 异常表现：将xdebug.remote_enable改为1后，执行php-fpm/xdebug start命令仍无法手动开启Xdebug
• 当前xdebug.ini配置：

xdebug.remote_host="host.docker.internal"
xdebug.remote_connect_back=0
xdebug.remote_port=9000
xdebug.idekey=PHPSTORM

xdebug.remote_autostart=0
xdebug.remote_enable=0
xdebug.cli_color=0
xdebug.profiler_enable=0
xdebug.profiler_output_dir="~/xdebug/phpstorm/tmp/profiling"

xdebug.remote_handler=dbgp
xdebug.remote_mode=req

xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
xdebug.var_display_max_depth=-1

解决步骤 #

1. 修正Xdebug 3.x的配置参数 #

Xdebug 3.x彻底更换了一批配置参数，你当前使用的是2.x的旧参数，这是命令失效的核心原因。将xdebug.ini替换为以下3.x适配配置：

xdebug.mode=debug
xdebug.client_host="host.docker.internal"
xdebug.client_port=9000
xdebug.idekey=PHPSTORM
xdebug.start_with_request=trigger
xdebug.cli_color=0
xdebug.profiler_enable=0
xdebug.profiler_output_dir="~/xdebug/phpstorm/tmp/profiling"
xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
xdebug.var_display_max_depth=-1

关键参数说明：

• xdebug.mode=debug：替代旧版xdebug.remote_enable=1，开启调试模式
• xdebug.client_host/xdebug.client_port：替代旧版remote_host/remote_port，指定IDE监听地址和端口
• xdebug.start_with_request=trigger：替代旧版remote_autostart=0，仅在触发时启动调试

2. 重启PHP-FPM容器 #

配置修改后必须重启容器才能生效：

docker-compose restart php-fpm

3. 验证Xdebug状态 #

进入workspace容器，执行以下命令确认Xdebug是否加载成功：

# 查看PHP版本及扩展信息
php -v
# 过滤Xdebug相关配置
php -i | grep Xdebug

如果输出中包含Xdebug版本及正确的参数配置，说明加载正常。

4. 重新执行启动命令 #

配置修正后，再次执行Laradock的Xdebug启动命令：

./php-fpm/xdebug start

执行后可通过docker-compose logs php-fpm查看容器日志，确认配置已更新并重启成功。

5. 额外排查点 #

• 检查Mac本地防火墙是否放行9000端口
• 确认IDE（如PHPStorm）已开启Xdebug监听，端口设置为9000
• 进入php-fpm容器内部，直接验证配置文件是否生效：

docker-compose exec php-fpm cat /usr/local/etc/php/conf.d/xdebug.ini

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