配置PHP Xdebug与VS Code实现断点调试：1. 安装并启用Xdebug扩展，通过php -m或phpinfo()验证；2. 在php.ini中添加Xdebug 3配置，设置mode=debug、client_host=127.0.0.1、client_port=9003；3. VS Code创建launch.json，配置type为php、port为9003，并正确设置pathMappings映射路径；4. 启动监听并设置断点，通过浏览器或CLI触发调试；5. 根据日志/tmp/xdebug.log排查连接问题，Docker环境需调整client_host为host.docker.internal。

安装并启用Xdebug扩展

确保你的PHP环境中已安装Xdebug扩展。可通过以下方式检查：

• 运行 php -m | grep Xdebug 查看是否已加载
• 或创建一个 phpinfo() 页面，在浏览器中打开，搜索“Xdebug”确认是否存在

如果未安装，可通过包管理器（如apt、brew）或手动下载编译安装。例如在Ubuntu上：

sudo apt install php-xdebug

安装完成后，编辑 php.ini 文件（或单独的 xdebug.ini），添加以下配置（适用于Xdebug 3）：

[XDebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log="/tmp/xdebug.log"

配置VS Code调试环境

在VS Code中打开你的PHP项目，进入调试视图，点击“创建 launch.json”文件，选择“PHP”环境。

生成的 .vscode/launch.json 应类似如下内容：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

• port 必须与 xdebug.client_port 一致
• pathMappings 用于映射服务器路径到本地项目路径，尤其在使用Docker或远程服务器时至关重要

启动调试并设置断点

在VS Code中完成配置后：

• 点击左侧调试图标，选择“Listen for Xdebug”配置
• 点击“启动监听”按钮（绿色三角）
• 在PHP代码中点击行号左侧设置断点（红点）
• 通过浏览器访问对应页面，或运行CLI脚本

当请求命中断点时，VS Code会自动暂停并高亮当前行，可查看变量、调用栈、逐行执行等。

常见问题排查

• 调试不触发：检查Xdebug是否启用，端口是否被占用，防火墙是否阻止
• 路径映射错误：确保 pathMappings 正确指向服务器中的实际路径
• 日志分析：查看 xdebug.log 文件，确认连接尝试和错误信息
• Docker环境：需将宿主机IP设为 xdebug.client_host，如使用Docker Desktop可用 host.docker.internal