通过SSH连接PhpStorm与Xdebug 3.1.2时连接超时求助

调试时出现报错：
Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: 10.10.59.4:9003 (through xdebug.client_host/xdebug.client_port) :-(

尝试通过SSH连接Xdebug，查阅大量资料仍未解决，求配置指导。

相关配置信息 #

1. php.ini配置 #

[xdebug]
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request = yes

2. /etc/php/7.4/mods-available/xdebug.ini配置 #

zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
;xdebug.trigger_value=1
xdebug.remote_autostart = 1
xdebug.remote_enable = 1
xdebug.remote_handler = dbgp
xdebug.remote_host = 127.0.0.1
xdebug.remote_log = /tmp/xdebug_remote.log
xdebug.remote_mode = req
xdebug.remote_port = 9003 #if you want to change the port you can change

3. 执行php -r "var_dump(phpversion('xdebug'));"的输出 #

Xdebug: [Step Debug] Could not connect to debugging client. Tried: 127.0.0.1:9003 (through xdebug.client_host/xdebug.client_port) :-( string(5) "3.1.2"

4. Xdebug及PHP详细配置信息 #

Xdebug: [Step Debug] Could not connect to debugging client. Tried: 127.0.0.1:9003 (through xdebug.client_host/xdebug.client_port) :-

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

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

             Enabled Features (through 'xdebug.mode' setting)              
Feature => Enabled/Disabled
Development Helpers => ✘ disabled
Coverage => ✘ disabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✔ enabled
Tracing => ✘ disabled

                            Optional Features                            
Compressed File Support => no
Clock Source => clock_gettime

                              Diagnostic Log                               
[Step Debug] WARN: Creating socket for '127.0.0.1:9003', poll success, but error: Operation now in progress (29).
[Step Debug] ERR: Could not connect to debugging client. Tried: 127.0.0.1:9003 (through xdebug.client_host/xdebug.client_port) :-

                              Step Debugging                               
Debugger is not active

                                   PHP                                    
                           Build Configuration                            
Version (Run Time) => 7.4.30
Version (Compile Time) => 7.4.27
Debug Build => no
Thread Safety => disabled
                                 Settings                                 
Configuration File (php.ini) Path => /etc/php/7.4/cli
Loaded Configuration File => /etc/php/7.4/cli/php.ini
Scan this dir for additional .ini files => /etc/php/7.4/cli/conf.d
Additional .ini files parsed => /etc/php/7.4/cli/conf.d/10-mysqlnd.ini,
/etc/php/7.4/cli/conf.d/10-opcache.ini,
/etc/php/7.4/cli/conf.d/10-pdo.ini,
/etc/php/7.4/cli/conf.d/15-xml.ini,
/etc/php/7.4/cli/conf.d/20-calendar.ini,
/etc/php/7.4/cli/conf.d/20-ctype.ini,
/etc/php/7.4/cli/conf.d/20-curl.ini,
/etc/php/7.4/cli/conf.d/20-dom.ini,
/etc/php/7.4/cli/conf.d/20-exif.ini,
/etc/php/7.4/cli/conf.d/20-ffi.ini,
/etc/php/7.4/cli/conf.d/20-fileinfo.ini,
/etc/php/7.4/cli/conf.d/20-ftp.ini,
/etc/php/7.4/cli/conf.d/20-gd.ini,
/etc/php/7.4/cli/conf.d/20-gettext.ini,
/etc/php/7.4/cli/conf.d/20-gmp.ini,
/etc/php/7.4/cli/conf.d/20-iconv.ini,
/etc/php/7.4/cli/conf.d/20-igbinary.ini,
/etc/php/7.4/cli/conf.d/20-imagick.ini,
/etc/php/7.4/cli/conf.d/20-imap.ini,
/etc/php/7.4/cli/conf.d/20-intl.ini,
/etc/php/7.4/cli/conf.d/20-json.ini,
/etc/php/7.4/cli/conf.d/20-mbstring.ini,
/etc/php/7.4/cli/conf.d/20-msgpack.ini,
/etc/php/7.4/cli/conf.d/20-mysqli.ini,
/etc/php/7.4/cli/conf.d/20-pdo_mysql.ini,
/etc/php/7.4/cli/conf.d/20-pdo_pgsql.ini,
/etc/php/7.4/cli/conf.d/20-pdo_sqlite.ini,
/etc/php/7.4/cli/conf.d/20-pgsql.ini,
/etc/php/7.4/cli/conf.d/20-phar.ini,
/etc/php/7.4/cli/conf.d/20-posix.ini,
/etc/php/7.4/cli/conf.d/20-propro.ini,
/etc/php/7.4/cli/conf.d/20-raphf.ini,
/etc/php/7.4/cli/conf.d/20-readline.ini,
/etc/php/7.4/cli/conf.d/20-shmop.ini,
/etc/php/7.4/cli/conf.d/20-simplexml.ini,
/etc/php/7.4/cli/conf.d/20-soap.ini,
/etc/php/7.4/cli/conf.d/20-sockets.ini,
/etc/php/7.4/cli/conf.d/20-sqlite3.ini,
/etc/php/7.4/cli/conf.d/20-sysvmsg.ini,
/etc/php/7.4/cli/conf.d/20-sysvsem.ini,
/etc/php/7.4/cli/conf.d/20-sysvshm.ini,
/etc/php/7.4/cli/conf.d/20-tokenizer.ini,
/etc/php/7.4/cli/conf.d/20-xdebug.ini,
/etc/php/7.4/cli/conf.d/20-xmlreader.ini,
/etc/php/7.4/cli/conf.d/20-xmlrpc.ini,
/etc/php/7.4/cli/conf.d/20-xmlwriter.ini,
/etc/php/7.4/cli/conf.d/20-xsl.ini,
/etc/php/7.4/cli/conf.d/20-zip.ini,
/etc/php/7.4/cli/conf.d/25-http.ini,
/etc/php/7.4/cli/conf.d/25-memcached.ini


Directive => Local Value => Master Value
xdebug.mode => debug => 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 => no value => no value
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 => 127.0.0.1 => 127.0.0.1
xdebug.client_port => 9003 => 9003
xdebug.discover_client_host => Off => Off
xdebug.client_discovery_header => no value => no value
xdebug.idekey => no value => no value
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
xdebug.remote_autostart => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_host => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_log => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_mode => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_port => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)

PhpStorm CLI解释器配置 #

配置为远程SSH解释器，对应PHP版本7.4.30，Xdebug版本3.1.2。

解决步骤 #

1. 清理Xdebug 2.x遗留配置 #

你的xdebug.ini中保留了Xdebug 2的废弃配置（remote_*系列参数），会干扰Xdebug 3的正常运行。修改/etc/php/7.4/mods-available/xdebug.ini，只保留Xdebug 3的有效配置：

zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.log=/tmp/xdebug.log

2. 配置SSH端口转发 #

通过SSH建立本地与远程服务器的端口转发，让远程Xdebug的请求能转发到本地PhpStorm：

• 在PhpStorm的SSH配置中添加本地端口转发：本地端口9003，目标地址127.0.0.1:9003
• 或手动执行SSH命令：

  ssh -L 9003:127.0.0.1:9003 你的远程服务器用户名@远程服务器IP
  

  保持该连接处于活跃状态。

3. 验证PhpStorm调试监听 #

• 点击PhpStorm右上角的调试监听按钮（电话图标），确保其变为绿色（处于监听状态）
• 进入Settings > Languages & Frameworks > PHP > Debug，确认Xdebug端口为9003，与配置一致
• 进入Settings > Languages & Frameworks > PHP > Servers，添加远程服务器映射，确保本地代码路径与远程服务器代码路径完全对应

4. 重启服务并验证 #

• 重启远程服务器的PHP服务：

  sudo systemctl restart php7.4-fpm
  

• 再次执行php -r "var_dump(phpversion('xdebug'));"，若配置正确，PhpStorm会弹出调试连接提示，且无连接错误。

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