You need to enable JavaScript to run this app.
最新活动
大模型
产品
解决方案
定价
生态与合作
支持与服务
开发者
了解我们

Docker环境下XDebug无法连接VSCode的调试问题求助

解决Docker + VSCode + XDebug连接失败的问题

我来帮你理一理这个问题,核心就是Docker容器和Windows主机之间的网络寻址错误,你踩的坑很多Docker新手都会遇到,别着急,按下面的步骤来排查修复:

关键问题分析

你用了xdebug.remote_connect_back=1,这个配置会让XDebug自动获取请求的REMOTE_ADDR作为调试主机地址,但容器里拿到的172.20.0.1其实是Docker网桥的网关IP,不是Windows主机的真实可访问IP。Windows的Docker网络结构里,容器要访问主机,得用DockerNAT网卡的IP(你这里是10.0.75.1)或者Docker提供的特殊域名host.docker.internal

具体修复步骤

  1. 修改XDebug配置,指定正确的调试主机
    打开你的php-ini-overrides.ini,做如下修改:

    upload_max_filesize = 100M
    post_max_size = 108M
    # added for debugging with Docker and VSCode
    xdebug.remote_enable=1
    # 注释掉remote_connect_back,因为它拿到的是网关IP,不是主机IP
    # xdebug.remote_connect_back=On
    # xdebug.remote_connect_back=1
    xdebug.remote_autostart=1
    # 使用Docker提供的特殊域名(Windows Docker支持),或者直接写你的DockerNAT IP 10.0.75.1
    xdebug.remote_host=host.docker.internal
    xdebug.remote_port=9001
    xdebug.profiler_enable=0
    xdebug.var_display_max_depth = 5
    xdebug.var_display_max_children = 256
    xdebug.var_display_max_data = 1024
    xdebug.remote_log = /application/xdebug.log
    xdebug.idekey = VSCODE
    
  2. 重启php-fpm容器让配置生效
    在主机终端执行:

    docker-compose restart php-fpm
    
  3. 验证容器到主机的网络连通性
    进入php-fpm容器,测试VSCode监听的9001端口是否能连通:

    docker-compose exec php-fpm bash
    nc -zv host.docker.internal 9001
    

    如果返回成功,说明网络通了;如果还是失败,就换成你的DockerNAT IP 10.0.75.1测试:

    nc -zv 10.0.75.1 9001
    
  4. 确认VSCode配置无误
    检查你的launch.json

    • port必须和XDebug的remote_port一致(都是9001)
    • pathMappings要确保容器内的路径和主机路径对应正确,你这里的"/application/public": "${workspaceRoot}/public"是对的,因为php-fpm容器的工作目录是/application
  5. 重新测试断点
    启动VSCode的调试监听,然后访问网页(用10.0.75.1:8000),应该就能触发断点了。

额外说明

  • host.docker.internal是Docker为Windows/macOS主机提供的特殊域名,自动映射到主机的IP,比手动写IP更灵活
  • 你之前关闭防火墙是对的,确保主机的9001端口没有被拦截
  • 从XDebug日志里能明确看到它一直在尝试连接172.20.0.1,这就是问题根源,修改remote_host后日志里应该会显示连接host.docker.internal或者10.0.75.1

内容的提问来源于stack exchange,提问作者Nico Kempe

火山引擎 最新活动