如何阻止Xdebug在未启用调试时持续尝试连接并记录错误？

问题原因 #

你的Xdebug配置中xdebug.start_with_request = yes会让Xdebug在每次HTTP请求时都自动尝试连接调试客户端，即使VS Code没有启动调试监听，它也会持续发起连接请求，从而产生日志报错。另外，配置里保留了Xdebug 2的旧版参数（remote_enable、remote_autostart等），这些在Xdebug 3中已被废弃，可能引发混淆。

解决方案 #

调整Xdebug配置，让它只在主动触发调试时才尝试连接客户端，具体步骤如下：

1. 更新php.ini配置 #

修改你的Xdebug配置项，保留必要的Xdebug 3参数，移除废弃的旧参数：

; Xdebug
xdebug.max_nesting_level = 256
xdebug.show_exception_trace = 0
xdebug.collect_params = 0
xdebug.mode = debug
xdebug.start_with_request = trigger
xdebug.client_host = ${LANDO_HOST_IP}
xdebug.client_port = 9003

关键参数说明 #

• xdebug.start_with_request = trigger：仅当存在调试触发信号时，Xdebug才会尝试连接调试客户端，避免无意义的连接尝试。
• 移除所有xdebug.remote_*开头的参数：这些是Xdebug 2的旧配置，Xdebug 3已不再使用，删除后可避免配置冲突。

2. 调试时的触发方式 #

需要调试时，通过以下方式触发Xdebug连接：

• 浏览器插件：安装Xdebug Helper（Chrome/Firefox），开启插件的调试模式，Xdebug会自动识别并发起连接。
• URL参数：在请求URL后添加?XDEBUG_SESSION_START=VSCODE，比如http://your-wp-site.local/?XDEBUG_SESSION_START=VSCODE。
• VS Code调试监听：启动VS Code的调试会话（点击绿色三角按钮），触发调试后Xdebug会自动连接到客户端。

验证修改 #

保存配置后，重启Lando环境：

lando restart

此时未启动调试时，WordPress日志中不会再出现Xdebug连接失败的报错，需要调试时触发即可正常连接。

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