VSCode中PHPDebug/Xdebug配置：Web服务器根目录设置问题

我的项目结构如下：

C:\WebAppRoot
C:\WebAppRoot\App
C:\WebAppRoot\App2
C:\WebAppRoot\SharedFiles\src
C:\WebAppRoot\SharedFiles\img

我在VSCode中加载C:\WebAppRoot\App作为项目，代码里引用SharedFiles目录下文件的方式是：

<script type="text/javascript" src="../SharedFiles/src/script.js">

但启动「Launch Built-in web server」后，这些文件找不到——因为内置服务器的根目录指向了C:\WebAppRoot\App。我想把服务器根目录改成C:\WebAppRoot，试了pathMappings等配置都没用，也搞不懂逻辑。

当前的launch.json配置如下：

{
    "name": "Launch Built-in web server",
    "type": "php",
    "request": "launch",
    "runtimeArgs": [
        "-dxdebug.mode=debug",
        "-dxdebug.start_with_request=yes",
        "-S",
        "localhost:0"
    ],
    "log": true,
    "program": "",
     "pathMappings": {
         "c:/WebAppRoot":"${workspaceRoot}",
    },
    "cwd": "${workspaceRoot}",
    "port": 9003,
    "serverReadyAction": {
        "pattern": "Development Server (http://localhost:([0-9]+)) started",
        "uriFormat": "http://localhost:%s",
        "action": "openExternally"
    }
}

解决方案 #

问题核心是PHP内置服务器的启动目录设置错误，以及pathMappings的映射逻辑搞反了，按以下步骤修改：

1. 修改cwd指定服务器根目录
   cwd决定了PHP内置服务器的启动根目录，把它改成WebAppRoot的路径。如果你的VSCode工作区是C:\WebAppRoot\App，可以用相对变量：

"cwd": "${workspaceFolder}/.."

也可以直接写绝对路径：

"cwd": "C:/WebAppRoot"

2. 修正pathMappings的映射关系
   pathMappings是给Xdebug用的，要把服务器端的路径映射到本地文件系统路径。现在服务器根是WebAppRoot，所以服务器上的/App对应本地的${workspaceFolder}（即C:\WebAppRoot\App），配置改成：

"pathMappings": {
    "/App": "${workspaceFolder}"
}

3. 调整访问URL指向App目录
   服务器根目录改成WebAppRoot后，要访问你的项目得加/App后缀，修改serverReadyAction的uriFormat：

"uriFormat": "http://localhost:%s/App"

4. 完整可用的launch.json

{
    "name": "Launch Built-in web server",
    "type": "php",
    "request": "launch",
    "runtimeArgs": [
        "-dxdebug.mode=debug",
        "-dxdebug.start_with_request=yes",
        "-S",
        "localhost:0"
    ],
    "log": true,
    "program": "",
    "pathMappings": {
        "/App": "${workspaceFolder}"
    },
    "cwd": "${workspaceFolder}/..",
    "port": 9003,
    "serverReadyAction": {
        "pattern": "Development Server (http://localhost:([0-9]+)) started",
        "uriFormat": "http://localhost:%s/App",
        "action": "openExternally"
    }
}

关键逻辑说明 #

• PHP内置服务器启动时，会把cwd设置的目录作为网站根目录，这样代码里的../SharedFiles就能正确找到WebAppRoot下的SharedFiles文件夹。
• pathMappings是让Xdebug关联服务器路径和本地文件，确保断点能命中本地的代码文件，搞反映射关系就会导致断点失效或路径错误。

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