使用VSCode+Xdebug调试Laravel Sail应用时遇错误求助

1. 容器内Xdebug未指向宿主机IP #

Laravel Sail运行在Docker容器中，Xdebug需要连接宿主机的调试端口，容器内的localhost并非宿主机地址。需在项目.env文件中添加配置：

SAIL_XDEBUG_MODE=debug
SAIL_XDEBUG_CONFIG="client_host=host.docker.internal client_port=9003 start_with_request=yes"

重启Sail使配置生效：

sail down && sail up -d

2. 清理冗余的launch.json配置 #

你的launch.json包含三个配置，但调试Laravel Sail仅需Listen for Xdebug这一项，另外两个配置是针对本地PHP脚本/内置服务器的，与容器环境无关，可注释或删除避免干扰。

清理后的示例：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "log": true // 可选，开启日志便于排查连接问题
        }
    ]
}

3. 确认Xdebug版本匹配 #

目前Sail镜像默认使用Xdebug3，对应调试端口为9003，VSCode的PHP Debug插件需支持Xdebug3版本，若使用Xdebug2则需将端口改为9000（不推荐，尽量保持与Sail默认配置一致）。

4. 检查端口占用与防火墙 #

确认宿主机9003端口未被其他程序占用，同时本地防火墙未阻止容器访问该端口：

# Windows
netstat -ano | findstr :9003

# macOS/Linux
lsof -i :9003

完成以上配置后，重启VSCode调试监听，刷新浏览器触发请求即可尝试进入断点。

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