Docker+PhpStorm环境下Xdebug重启监听后无法调试后台PHP脚本

问题背景 #

基于Ubuntu镜像的PHP 7.1、Xdebug 2及Docker环境，后台运行的server.php通过RabbitMQ触发Symfony应用执行。容器重启时Xdebug可正常命中断点，但关闭PhpStorm监听再重新开启后，无法命中断点——容器内Xdebug与服务运行正常，且已设置最大并发连接数为20。

问题根源 #

server.php使用pcntl_fork()创建子进程处理RabbitMQ任务，Xdebug的调试连接是进程级绑定的：

• 容器启动时，父进程初始化Xdebug连接配置，子进程会继承该连接状态
• 当PhpStorm关闭监听再重启后，已存在的子进程无法主动重新建立新的Xdebug连接，因为它们的Xdebug会话是启动时初始化的，不会自动重置

解决方案 #

1. 子进程任务前强制重置Xdebug连接 #

在server.php的子进程逻辑（执行$amqp()之前）添加Xdebug重置代码，确保每次处理任务时都尝试重新连接IDE：

} else {
    $appstate = \Phalcon\Di::getDefault()->get('app.state');
    $appstate->setWork(false);
    registerSigHandlers();

    // 重置Xdebug连接，强制重新连接IDE
    if (function_exists('xdebug_stop_debugger')) {
        xdebug_stop_debugger();
    }
    ini_set('xdebug.remote_autostart', 1);
    if (function_exists('xdebug_break')) {
        xdebug_break();
    }

    $amqp();
    exit(1);
}

2. 给启动脚本添加信号触发子进程重启逻辑 #

当前启动脚本的my_handler()为空，修改它以支持通过SIGUSR1信号重启所有子进程，让新子进程重新初始化Xdebug连接：
修改启动脚本中的my_handler函数：

# SIGUSR1-handler
my_handler() {
  echo "Received SIGUSR1, restarting worker processes..."
  # 终止所有子进程
  pkill -P $pid
  # 等待所有子进程退出
  while true; do
    local exit_status
    pcntl_wait(exit_status)
    if [ $? -eq -1 ]; then
      break
    fi
  done
  workers=0
  echo "Workers restarted successfully."
}

当PhpStorm重启监听后，在主机上执行以下命令触发子进程重启：

# 获取容器ID
CONTAINER_ID=$(docker ps --filter "name=userapi-server-php" --format "{{.ID}}")
# 发送SIGUSR1信号
docker kill -s SIGUSR1 $CONTAINER_ID

3. 优化Xdebug配置（排除版本混淆问题） #

Xdebug 2不支持xdebug.mode配置项，移除该配置避免干扰，同时调高日志等级方便排查：
修改xdebug.ini：

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.idekey=PHPSTORM
xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0
xdebug.remote_port=9003
xdebug.remote_log=/opt/userapi-app/tmp/xdebug.log
xdebug.log_level=7 # 调试完成后可改回0

验证步骤 #

1. 重启Docker容器，确认初始状态下调试可正常命中断点
2. 关闭PhpStorm的Xdebug监听，再重新开启
3. 执行上述docker kill -s SIGUSR1命令触发子进程重启
4. 触发RabbitMQ任务，检查是否能正常命中断点

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