Laravel 10 Sail Ubuntu环境下Xdebug与VSCode调试失败求助

1. 修复Linux下host.docker.internal解析问题 #

Linux系统默认不支持host.docker.internal域名解析，需手动替换为宿主机内网IP：

• 查看宿主机内网IP（通常为192.168.x.x或172.x.x.x）：

  ip addr show docker0 | grep -Po 'inet \K[\d.]+'
  

• 修改项目根目录的.env文件，将XDEBUG_HOST替换为上述获取到的IP：

  XDEBUG_HOST=你的宿主机内网IP
  

• 重启Sail容器使配置生效：

  sail down && sail up -d
  

2. 排查端口占用与防火墙拦截 #

• 检查宿主机9003端口是否被其他进程占用：

  sudo lsof -i :9003
  

  若有占用，可终止对应进程，或修改Xdebug端口（同步更新.env的XDEBUG_PORT和VSCode的launch.json端口配置）。
• 临时关闭Ubuntu防火墙测试连接：

  sudo ufw disable
  

  若关闭后可正常连接，需添加防火墙规则放行9003端口：

  sudo ufw allow 9003/tcp
  sudo ufw enable
  

3. 验证Xdebug核心配置 #

确保容器内php.ini（或xdebug.ini）的关键配置正确：

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=${XDEBUG_HOST}
xdebug.client_port=${XDEBUG_PORT}
xdebug.log=/var/www/html/storage/logs/xdebug.log

开启日志后，可查看storage/logs/xdebug.log中的具体错误信息，定位连接失败原因。

4. 修正VSCode launch.json配置 #

确保调试配置与容器内Xdebug参数匹配：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "log": true
        }
    ]
}

• pathMappings必须准确映射容器内代码路径（/var/www/html）到本地项目根目录。
• 开启log可在VSCode调试控制台查看日志，排查连接请求是否到达宿主机。

5. 确认Sail容器的Xdebug状态 #

进入容器验证Xdebug是否正确加载：

sail exec php php -v

输出中需包含with Xdebug x.x.x字样。若未出现，说明Xdebug未正确安装，执行以下命令重新构建容器：

sail build --no-cache

6. 测试Xdebug连接 #

在项目中添加测试路由并调用xdebug_info();，访问路由后查看Xdebug日志和VSCode调试控制台输出，确认连接请求是否正常发起。

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