Docker环境下VS Code远程Xdebug会话超10分钟自动断开问题

你遇到的10分钟（600秒）闲置后Xdebug会话断开，核心原因大概率是网络层的闲置超时机制触发，结合日志里的「Broken pipe」错误，具体可能是以下几点：

• Docker容器/宿主机的TCP连接闲置超时：默认很多环境的TCP保活配置是600秒，闲置超过这个时间会主动断开连接
• Xdebug与VS Code之间缺少心跳维持：默认Xdebug不会发送心跳包，长时间闲置时中间网络节点会认为连接已死
• VS Code调试客户端的超时限制：PHP调试插件可能存在默认超时设置，闲置过久会主动终止会话

1. 开启Xdebug心跳机制 #

在xdebug.ini中添加心跳配置，让Xdebug定期发送心跳包维持连接，设置值小于600秒即可（比如300秒/5分钟）：

zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.client_heartbeat=300  # 新增：每300秒发送一次心跳

2. 调整Docker容器的TCP保活参数 #

在docker-compose.local.yml的app服务中添加sysctls配置，覆盖容器内的TCP保活规则，避免网络层断开：

services:
  app:
    # 原有配置...
    sysctls:
      - net.ipv4.tcp_keepalive_time=300  # 连接闲置300秒后开始发送保活包
      - net.ipv4.tcp_keepalive_intvl=60   # 每60秒发一次保活包
      - net.ipv4.tcp_keepalive_probes=5   # 连续5次没收到响应才断开

3. 延长VS Code调试超时时间 #

在VS Code的launch.json调试配置中添加timeout参数，设置足够大的超时值（比如3600000毫秒=1小时）：

{
    "name": "AppName Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/": "${workspaceFolder}/app_name"
    },
    "timeout": 3600000  # 新增：超时时间设为1小时
}

4. 排查PHPUnit本身的超时设置 #

检查phpunit.xml中是否存在测试超时配置，确保不会因为闲置终止测试进程：

<!-- 确保没有设置过短的超时，比如以下配置如果存在，调整或移除 -->
<!-- <phpunit ... timeoutForSmallTests="600"> -->

修改配置后重启Docker容器和VS Code调试会话，故意闲置超过10分钟，观察：

• VS Code调试会话是否保持连接
• Xdebug日志（级别设为3）是否不再出现「Broken pipe」错误
• 测试进程是否仍处于暂停状态，可手动恢复执行

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