Ubuntu下Xdebug+VSCode调试PHP时全局超变量值异常求助

环境信息 #

• PHP 8.1
• Ubuntu 22.04
• Visual Studio Code

php -v执行结果 #

PHP 8.1.2 (cli) (built: Jul 21 2022 12:10:37) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Xdebug v3.1.2, Copyright (c) 2002-2021, by Derick Rethans
    with Zend OPcache v8.1.2, Copyright (c), by Zend Technologies

VSCode调试启动配置 #

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000,
            "runtimeExecutable": "/usr/bin/php",
            "pathMappings": {
                "/var/www": "${workspaceFolder}"
            }
        }
    ]
}

问题：$_SERVER变量值异常 #

Xdebug能正常单步执行，但全局超变量$_SERVER的值和浏览器访问时完全不同，像是读取了系统全局变量而非Web环境变量。例如：

Firefox访问localhost时的$_SERVER片段： #

[HTTP_HOST] => localhost[HTTP_USER_AGENT] => Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0  
[HTTP_ACCEPT] => text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8 
[HTTP_ACCEPT_LANGUAGE] => en-US,en;q=0.5 [HTTP_ACCEPT_ENCODING] => gzip, deflate, br 
[HTTP_CONNECTION] => keep-alive 
[SERVER_SIGNATURE] =>Apache/2.4.52 (Ubuntu) Server at localhost Port 80
[SERVER_SOFTWARE] => Apache/2.4.52 (Ubuntu) 
[SERVER_NAME] => localhost 
[SERVER_ADDR] => 127.0.0.1 
[SERVER_PORT] => 80 [REMOTE_ADDR] => 127.0.0.1 
[DOCUMENT_ROOT] => /var/www/html
....

Xdebug调试时的$_SERVER片段： #

[GJS_DEBUG_TOPICS] => JS ERROR;JS LOG
[LANGUAGE] => en_US:en
[USER] => viet
[LC_TIME] => en_CA.UTF-8
[XDG_SESSION_TYPE] => x11
[SHLVL] => 0
[HOME] => /home/viet
[DESKTOP_SESSION] => ubuntu
[GIO_LAUNCHED_DESKTOP_FILE] => /usr/share/applications/code.desktop
[GTK_MODULES] => gail:atk-bridge
[GNOME_SHELL_SESSION_MODE] => ubuntu
...
[VSCODE_AMD_ENTRYPOINT] => vs/workbench/api/node/extensionHostProcess
[VSCODE_HANDLES_UNCAUGHT_ERRORS] => true
[XDEBUG_MODE] => debug,develop
[XDEBUG_CONFIG] => client_port=40151
[PHP_SELF] => /var/www/html/pages/automation/index.php
[SCRIPT_NAME] => /var/www/html/pages/automation/index.php
[SCRIPT_FILENAME] => /var/www/html/pages/automation/index.php
[PATH_TRANSLATED] => /var/www/html/pages/automation/index.php
[DOCUMENT_ROOT] => 
[REQUEST_TIME_FLOAT] => 1659989701.6132
[REQUEST_TIME] => 1659989701

其中DOCUMENT_ROOT为空，明显不是Web环境下的变量值，请问如何修复？

更新：使用“Listen for XDebug”配置无法触发断点 #

按照建议切换到“Listen for XDebug”配置后，VS Code一直处于监听状态，但用Chrome搭配Xdebug helper扩展访问页面时，完全无法触发断点。

当前/etc/php/8.1/cli/php.ini配置内容：

zend_extension="xdebug.so";
xdebug.remote_autostart=1
xdebug.remote_log=/var/log/apache2/xdebug.log
xdebug.default_enable = 1
xdebug.remote_enable=1
xdebug.remote_port=9003
xdebug.idekey = VSCODE
xdebug.mode=debug
xdebug.start_with_request = yes

解决方案 #

1. $_SERVER变量异常的根源 #

你当前使用的Launch currently open script配置是通过CLI模式运行PHP脚本，而非Web服务器（Apache）环境，所以$_SERVER会包含系统环境变量，而非Web请求相关变量。要获取Web环境下的$_SERVER，必须通过Web服务器触发调试，也就是使用Listen for XDebug配置。

2. 修复断点无法触发的问题 #

你的Xdebug配置混用了Xdebug 2和Xdebug 3的参数，这是核心问题。Xdebug 3已废弃所有remote_*开头的参数，需改用新参数，具体调整步骤如下：

步骤1：修改Apache对应的PHP配置文件

注意：你当前修改的是CLI模式的/etc/php/8.1/cli/php.ini，但Web服务器使用的是/etc/php/8.1/apache2/php.ini，必须修改该文件的Xdebug配置：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1
xdebug.idekey=VSCODE
xdebug.log=/var/log/apache2/xdebug.log

• 移除所有remote_*开头的参数（如xdebug.remote_autostart、xdebug.remote_enable），这些是Xdebug 2的参数，Xdebug 3不识别。
• 确保xdebug.client_port=9003与VSCode配置的端口一致。

步骤2：重启Apache服务器

执行命令：

sudo systemctl restart apache2

步骤3：调整VSCode调试配置

确保Listen for XDebug配置添加路径映射，保证本地代码与服务器路径对应：

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www": "${workspaceFolder}"
    }
}

步骤4：确认Xdebug Helper扩展设置

在Chrome的Xdebug Helper扩展中，设置IDE Key为VSCODE，与配置里的xdebug.idekey一致，并开启调试模式。

步骤5：验证调试功能

访问目标页面（如http://localhost/pages/automation/index.php），查看VSCode是否触发断点，此时$_SERVER变量应与浏览器访问时一致。

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