Windows11下VSCode中Xdebug与本地主机连接调试问题

• 原Windows10环境下可通过VSCode+PHP Debug+Xdebug实现PHP脚本断点调试，更换Windows11后无法与浏览器交互调试
• 三种调试模式异常情况：
  • Listen for Xdebug：浏览器访问localhost无法与VSCode建立连接
  • Launch Built-in web server：浏览器能启动但断点不触发
  • Launch currently open script：断点可触发，但无法与localhost/debug页面交互
• 已统一端口为9003，netstat显示Listen模式下9000端口被Code.exe占用

• PHP Debug扩展版本：v1.32.1
• PHP版本：8.2.4.0
• Xdebug版本：3.2.1
• XAMPP的Apache、MySQL已正常启动，浏览器访问localhost/debug可显示XAMPP图标

launch.json #

{    
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        
        { // port was previously as 0
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        },
        {
            "name": "Launch Built-in web server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:0"
            ],
            "program": "",
            "cwd": "${workspaceRoot}",
            "port": 9003,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

xdebug_info()输出 #

Version 3.2.1
Support Xdebug on Patreon, GitHub, or as a business
Enabled Features
(through 'xdebug.mode' setting)
Feature Enabled/Disabled    Docs
Development Helpers ✔ enabled   ⊕
Coverage    ✘ disabled  ⊕
GC Stats    ✘ disabled  ⊕
Profiler    ✘ disabled  ⊕
Step Debugger   ✘ disabled  ⊕
Tracing ✘ disabled  ⊕
Optional Features
Compressed File Support yes (gzip)
Clock Source    GetSystemTimePreciseAsFileTime
'xdebug://gateway' pseudo-host support  no
'xdebug://nameserver' pseudo-host support   no
Systemd Private Temp Directory  not enabled
Diagnostic Log
No messages
PHP
Build Configuration
Version (Run Time)  8.2.4
Version (Compile Time)  8.2.4
Debug Build no
Thread Safety   enabled
Thread API  Windows Threads
Settings
Configuration File (php.ini) Path   no value
Loaded Configuration File   C:\xampp\php\php.ini
Scan this dir for additional .ini files (none)
Additional .ini files parsed    (none)
Directive   Local Value Master Value    Docs
xdebug.cli_color    0   0   ⊕
xdebug.client_discovery_header  HTTP_X_FORWARDED_FOR,REMOTE_ADDR    HTTP_X_FORWARDED_FOR,REMOTE_ADDR    ⊕
xdebug.client_host  localhost   localhost   ⊕
xdebug.client_port  9003    9003    ⊕
xdebug.cloud_id no value    no value    ⊕
xdebug.collect_assignments  Off Off ⊕
xdebug.collect_return   Off Off ⊕
xdebug.connect_timeout_ms   200 200 ⊕
xdebug.discover_client_host 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.file_link_format no value    no value    ⊕
xdebug.filename_format  no value    no value    ⊕
xdebug.force_display_errors Off Off ⊕
xdebug.force_error_reporting    0   0   ⊕
xdebug.gc_stats_output_name gcstats.%p  gcstats.%p  ⊕
xdebug.halt_level   0   0   ⊕
xdebug.idekey   VSCODE  VSCODE  ⊕
xdebug.log  no value    no value    ⊕
xdebug.log_level    7   7   ⊕
xdebug.max_nesting_level    256 256 ⊕
xdebug.max_stack_frames -1  -1  ⊕
xdebug.mode develop develop ⊕
xdebug.output_dir   C:\Windows\Temp C:\Windows\Temp ⊕
xdebug.profiler_append  Off Off ⊕
xdebug.profiler_output_name cachegrind.out.%p   cachegrind.out.%p   ⊕
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_mode  (setting renamed in Xdebug 3)   (setting renamed in Xdebug 3)   ⊕
xdebug.remote_port  (setting renamed in Xdebug 3)   (setting renamed in Xdebug 3)   ⊕
xdebug.scream   Off Off ⊕
xdebug.show_error_trace Off Off ⊕
xdebug.show_exception_trace Off Off ⊕
xdebug.show_local_vars  Off Off ⊕
xdebug.start_upon_error default default ⊕
xdebug.start_with_request   default default ⊕
xdebug.trace_format 0   0   ⊕
xdebug.trace_options    0   0   ⊕
xdebug.trace_output_name    trace.%c    trace.%c    ⊕
xdebug.trigger_value    no value    no value    ⊕
xdebug.use_compression  1   1   ⊕
xdebug.var_display_max_children 128 128 ⊕
xdebug.var_display_max_data 512 512 ⊕
xdebug.var_display_max_depth    3   3   ⊕

php.ini配置 #

[Zend Modules]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=localhost
xdebug.remote_port=9003

[XDebug]
zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=localhost
xdebug.remote_port=9003
xdebug.idekey=VSCODE
[Syslog]

1. 修复php.ini的Xdebug 3配置 #

Xdebug 3已废弃remote_*系列配置，全部改用新参数，直接替换[XDebug]区块内容：

[XDebug]
zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
xdebug.mode = debug,develop
xdebug.start_with_request = yes
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.idekey = VSCODE

删除[Zend Modules]下的所有Xdebug相关配置，避免冲突。

2. 调整VSCode的launch.json配置 #

针对Listen for Xdebug模式 #

确保端口和php.ini一致，无需额外修改，但需注意：

• 启动VSCode的调试监听后，浏览器访问PHP文件时，xdebug.start_with_request=yes会自动触发调试
• 检查Windows防火墙是否允许VSCode接收9003端口的连接

针对Launch Built-in web server模式 #

修改runtimeArgs中的端口指定，避免随机端口问题，同时确保直接打开当前编辑的PHP文件：

{
    "name": "Launch Built-in web server",
    "type": "php",
    "request": "launch",
    "runtimeArgs": [
        "-dxdebug.mode=debug",
        "-dxdebug.start_with_request=yes",
        "-S",
        "localhost:8080"
    ],
    "program": "",
    "cwd": "${workspaceRoot}",
    "port": 9003,
    "serverReadyAction": {
        "pattern": "Development Server \\(http://localhost:8080\\) started",
        "uriFormat": "http://localhost:8080/${relativeFile}",
        "action": "openExternally"
    }
}

3. 解决端口占用问题 #

netstat显示9000端口被Code.exe占用，执行以下操作：

• 关闭VSCode所有调试会话，重启VSCode
• 暂时禁用无关扩展，排查是否有其他扩展占用端口

4. 验证配置生效 #

重启XAMPP的Apache服务，执行php -v确认Xdebug 3.2.1已加载；再次访问xdebug_info()页面，确认Step Debugger显示为enabled。

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