VSCode配置PHP Xdebug调试时反复报9111端口EADDRINUSE占用错误

启动VSCode Xdebug调试时反复弹出listen EADDRINUSE: address already in use :::9111报错；提前排查系统层面9111端口无外部程序占用，手动结束所有疑似占用进程、更换其他调试端口后依然报相同错误。

• VSCode PHP Debug插件的残留内存锁：前一次调试异常退出时，插件会在后台持有端口绑定的系统权限，哪怕系统层面已经看不到对应端口的占用进程，内存中的锁未释放时，再次启动调试依然会判定端口被占用；更换端口报错本质是插件初始化时把旧的锁逻辑套用到了新端口上，和目标端口本身是否被占没有关系。
• launch.json内部配置抢占：当前配置文件里两个调试项都硬绑定了同一个9111固定端口，插件初始化时会对两个配置项依次做端口绑定，相当于同一个端口被插件自身的两个逻辑抢占，直接触发EADDRINUSE。
• Xdebug配置重复预绑定：php.ini中同时存在旧版Xdebug2、新版Xdebug3的重复端口配置项，PHP进程启动时会按照双份配置提前在本地做端口预绑定，反过来和VSCode的监听逻辑抢同一个端口的使用权。

1. 彻底清理VSCode残留端口锁
   不要仅关闭VSCode窗口，要从系统托盘退出所有VSCode进程，打开任务管理器结束全部残留的Code.exe进程，等待10秒确认内存锁完全释放后再重新启动VSCode；启动后先在扩展面板找到PHP Debug插件，点击重启按钮重置插件的端口绑定逻辑。
2. 修正launch.json的端口冲突
   调整两个调试配置的端口绑定规则，避免硬绑定同一个固定端口：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Listen for Xdebug",
               "type": "php",
               "request": "launch",
               "port": 9111
           },
           {
               "name": "Launch currently open script",
               "type": "php",
               "request": "launch",
               "program": "${file}",
               "cwd": "${fileDirname}",
               "port": 0,
               "runtimeArgs": [
                   "-dxdebug.start_with_request=yes"
               ]
           }
       ]
   }
   

   其中本地脚本调试项的端口值设为0，代表让插件自动分配无冲突的随机端口，从根源上避免两个配置抢固定端口的问题。
3. 清理php.ini中的冗余Xdebug配置
   先确认本地安装的Xdebug版本，删除跨版本的重复配置项，避免PHP进程启动时预绑定端口：
   • 如果使用Xdebug3版本：删除所有xdebug.remote_*开头的旧版配置，只保留和VSCode监听端口一致的xdebug.client_port配置，补充设置xdebug.mode=debug指定调试模式。
   • 如果使用Xdebug2版本：删除xdebug.client_port这类新版专属配置，保留xdebug.remote_port即可。
     配置修改完成后重启PHP关联的Web服务，让新配置完全生效。

配置调整完成后，先选择“Listen for Xdebug”配置启动调试，确认VSCode底部状态栏显示调试监听已激活的状态，再访问PHP页面触发调试流程，不要同时启动多个调试配置项。

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