Windows10环境下Docker+VSCode配置Xdebug（Laravel项目）端口占用无输出求助

核心问题定位 #

1. 端口冲突：Windows环境下9000端口常被本机PHP-FPM、Web服务等默认占用，所以VSCode调试器启动时会报EADDRINUSE错误
2. Xdebug配置版本不兼容：你使用的PHP8.0对应安装的是Xdebug3.x版本，当前配置全是Xdebug2的废弃参数，无法正常建立调试连接，所以没有调试输出

修复步骤 #

1. 修改Dockerfile中的Xdebug配置

替换原有Xdebug安装配置段为Xdebug3兼容配置：

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug \
    && echo "\n\
    xdebug.mode = debug \n\
    xdebug.start_with_request = yes \n\
    xdebug.client_host = host.docker.internal \n\
    xdebug.client_port = 9003 \n\
    xdebug.log = /tmp/xdebug.log \n\
    " >> /usr/local/etc/php/conf.d/docker-php-xdebug.ini

说明：

• 用host.docker.internal代替写死的局域网IP，Docker Desktop会自动解析为Windows宿主机地址，适配不同网络环境
• 端口改为9003，避开常用的9000端口，解决端口占用问题
• 全部使用Xdebug3官方有效参数，移除已经废弃的remote_前缀配置

2. 修改VSCode的launch.json配置

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug on Docker App",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

说明：

• 监听端口同步修改为9003
• 路径映射用内置变量${workspaceFolder}代替硬编码的本地路径，避免路径写错的问题，适配不同开发环境

3. 生效配置&验证

• 删除原有容器、重建Docker镜像，确保新的Xdebug配置生效
• 启动VSCode调试监听，在Laravel入口文件或者路由处打断点，访问项目地址即可命中调试

额外排查方案 #

如果还是无法连接，进入容器执行cat /tmp/xdebug.log查看Xdebug运行日志，定位具体连接错误。如果9003端口仍有占用，可将两端的端口同步替换为其他未占用端口（比如9004、9005）即可。

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