Docker中Xdebug无法建立连接问题排查求助

调试时出现错误提示：Connection was not established. Probably 'xdebug.remote_host=host.docker.internal'，查阅多篇资料后仍未解决。

容器启动命令 #

docker run --rm -it -v $(pwd):/app -v $(pwd)/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini jitesoft/phpunit /bin/ash

自定义xdebug.ini配置 #

;
; NOTE: We want to echo these contents to this file location
;
;     PATH: /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
;

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so

xdebug.mode=debug
xdebug.idekey=PHPSTORM
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log=/var/log/xdebug.log

Xdebug调试配置输出 #

__   __   _      _                 
\ \ / /  | |    | |                
 \ V / __| | ___| |__  _   _  __ _ 
  > < / _` |/ _ \ '_ \| | | |/ _` |
 / . \ (_| |  __/ |_) | |_| | (_| |
/_/ \_\__,_|\___|_.__/ \__,_|\__, |
                              __/ |
                             |___/ 

Version => 3.2.0
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support

          Enabled Features (through 'XDEBUG_MODE' env variable)          
Feature => Enabled/Disabled
Development Helpers => ✘ disabled
Coverage => ✔ enabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✘ disabled
Tracing => ✘ disabled

                            Optional Features                            
Compressed File Support => no
Clock Source => clock_gettime
'xdebug://gateway' pseudo-host support => yes
'xdebug://nameserver' pseudo-host support => no
Systemd Private Temp Directory => not enabled

                              Diagnostic Log                              
No messages

                                   PHP                                   
                           Build Configuration                           
Version (Run Time) => 8.2.1
Version (Compile Time) => 8.2.1
Debug Build => no
Thread Safety => disabled
                                 Settings                                 
Configuration File (php.ini) Path => /usr/local/etc/php
Loaded Configuration File => (none)
Scan this dir for additional .ini files => /usr/local/etc/php/conf.d
Additional .ini files parsed => /usr/local/etc/php/conf.d/date_timezone.ini,
/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini,
/usr/local/etc/php/conf.d/memory-limit.ini


Directive => Local Value => Master Value
xdebug.mode (through XDEBUG_MODE) => coverage => debug
xdebug.start_with_request => yes => yes
xdebug.start_upon_error => default => default
xdebug.output_dir => /tmp => /tmp
xdebug.use_compression => 0 => 0
xdebug.trigger_value => no value => no value
xdebug.file_link_format => no value => no value
xdebug.filename_format => no value => no value
xdebug.log => /var/log/xdebug.log => /var/log/xdebug.log
xdebug.log_level => 7 => 7
xdebug.var_display_max_children => 128 => 128
xdebug.var_display_max_data => 512 => 512
xdebug.var_display_max_depth => 3 => 3
xdebug.max_nesting_level => 256 => 256
xdebug.cli_color => 0 => 0
xdebug.force_display_errors => Off => Off
xdebug.force_error_reporting => 0 => 0
xdebug.halt_level => 0 => 0
xdebug.max_stack_frames => -1 => -1
xdebug.show_error_trace => Off => Off
xdebug.show_exception_trace => Off => Off
xdebug.show_local_vars => Off => Off
xdebug.dump.COOKIE => no value => no value
xdebug.dump.ENV => no value => no value
xdebug.dump.FILES => no value => no value
xdebug.dump.GET => no value => no value
xdebug.dump.POST => no value => no value
xdebug.dump.REQUEST => no value => no value
xdebug.dump.SERVER => no value => no value
xdebug.dump.SESSION => no value => no value
xdebug.dump_globals => On => On
xdebug.dump_once => On => On
xdebug.dump_undefined => Off => Off
xdebug.profiler_output_name => cachegrind.out.%p => cachegrind.out.%p
xdebug.profiler_append => Off => Off
xdebug.cloud_id => no value => no value
xdebug.client_host => host.docker.internal => host.docker.internal
xdebug.client_port => 9003 => 9003
xdebug.discover_client_host => Off => Off
xdebug.client_discovery_header => HTTP_X_FORWARDED_FOR,REMOTE_ADDR => HTTP_X_FORWARDED_FOR,REMOTE_ADDR
xdebug.idekey => PHPSTORM => PHPSTORM
xdebug.connect_timeout_ms => 200 => 200
xdebug.scream => Off => Off
xdebug.gc_stats_output_name => gcstats.%p => gcstats.%p
xdebug.trace_output_name => trace.%c => trace.%c
xdebug.trace_format => 0 => 0
xdebug.trace_options => 0 => 0
xdebug.collect_assignments => Off => Off
xdebug.collect_return => Off => Off

调试执行控制台输出 #

[docker://jitesoft/phpunit:latest/]:php -dxdebug.mode=debug -dxdebug.client_port=9000 -dxdebug.client_host=host.docker.internal -dxdebug.client_host=host.docker.internal /opt/project/index.php

Process finished with exit code 0

发现的异常点 #

• 调试配置输出显示Step Debugger仍处于禁用状态
• 调试执行的脚本路径为/opt/project/index.php，但本地挂载路径为/app，正确路径应为/app/index.php

解决思路 #

针对Step Debugger禁用问题 #

1. 配置输出显示xdebug.mode的Local Value是coverage，Master Value是debug，说明环境变量XDEBUG_MODE覆盖了配置文件设置。需在容器启动时显式设置环境变量：

   docker run --rm -it -e XDEBUG_MODE=debug -v $(pwd):/app -v $(pwd)/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini jitesoft/phpunit /bin/ash
   

2. 进入容器后执行php -v或xdebug_info()，确认Step Debugger是否已启用。

针对脚本路径错误问题 #

1. 在IDE调试配置中，将容器内脚本路径修正为/app/index.php，与本地挂载路径保持一致。
2. 检查IDE的Docker映射配置，确认本地目录与容器/app的映射关系未被覆盖。

附加排查步骤 #

1. 统一端口：Xdebug 3默认端口为9003，但调试命令指定了9000，需确保IDE监听端口与Xdebug配置端口一致。
2. 验证宿主机解析：进入容器执行ping host.docker.internal，若解析失败，直接替换为宿主机实际IP。
3. 查看Xdebug日志：检查/var/log/xdebug.log，获取连接失败的具体原因（如超时、拒绝连接等）。

内容的提问来源于stack exchange，提问作者Alex.Barylski