PHP开启Xdebug详细配置教程

本文详细讲解了PHP环境下Xdebug 3的安装确认、核心配置与实战调试全流程，涵盖如何通过php -v和phpinfo()快速验证是否启用、php.ini中必须设置的zend_extension路径及xdebug.mode=debug等关键参数、浏览器端触发断点的两种可靠方式（URL参数或插件），以及VS Code中launch.json的精准配置要点——特别是端口一致性（默认9003）和pathMappings路径映射的易错细节；针对本地开发、Docker、WSL等不同环境的网络与路径差异，文章也给出了实用避坑指南，帮你彻底摆脱“断点不命中”“连接被拒绝”等常见调试困境。

PHP怎么确认Xdebug是否已安装

直接在命令行运行 php -v，如果输出里带 Xdebug 和版本号（比如 Xdebug v3.3.1），说明已加载；没看到就代表没装或没启用。也可以写个 phpinfo() 页面打开看——搜索 xdebug，有模块信息才作数。注意：Xdebug 3 和 2 的配置项、函数名、INI 文件写法完全不同，别混用。

PHP.ini里怎么加Xdebug配置（Xdebug 3）

Xdebug 3 默认不开启远程调试，必须手动配。找到你的 php.ini（用 php --ini 查路径），在末尾追加：

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

关键点：

• zend_extension 必须指向实际的 .so（Linux/macOS）或 .dll（Windows）文件路径，不能只写 xdebug（除非你用了自动加载机制）
• xdebug.mode=debug 是 Xdebug 3 的核心开关，不是 zend_extension 开了就自动调试
• xdebug.client_port 默认是 9003，不是旧版的 9000；VS Code、PhpStorm 默认连 9003，端口不匹配会“连接被拒绝”
• 开发机用 127.0.0.1，Docker 容器里调试宿主机 PHP，得设成宿主机网关（比如 172.17.0.1）

为什么浏览器访问PHP页面没触发断点

常见原因不是配置错，而是没发调试指令。Xdebug 3 不再默认监听所有请求，必须显式触发：

• 在 URL 后加 ?XDEBUG_SESSION_START=1（任意值都行），例如 http://localhost/test.php?XDEBUG_SESSION_START=1
• 或者装浏览器插件（如 Xdebug Helper），点图标激活，它会自动塞 cookie 或 query 参数
• 如果用了 xdebug.start_with_request=yes，那每次请求都会尝试连 IDE，但前提是 IDE 已启动并监听中——否则 Xdebug 会等几秒后放弃，不报错也不提示
• 检查 xdebug.log：加一行 xdebug.log=/tmp/xdebug.log，看日志里有没有 Connection to client failed 或 Connected to debugging client

VS Code里怎么让Xdebug真正停下来

光装 PHP Debug 插件不够，还得配 launch.json。项目根目录下 .vscode/launch.json 至少要有：

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

重点：

• port 必须和 php.ini 里的 xdebug.client_port 一致
• pathMappings 是关键：左边是服务器上 PHP 文件的绝对路径（比如 Docker 容器里是 /var/www/html/index.php），右边是本地代码路径；映射错会导致断点灰色、不命中
• 启动调试前，先点 VS Code 左上角 ▶️ 图标（开始调试），再刷新网页；顺序反了，请求就发出去了，IDE 还没准备好

复杂点在于路径映射和网络拓扑——本地开发、Homestead、Docker、WSL 各自的路径和 IP 规则不同，一个配置打天下基本不可能。

到这里，我们也就讲完了《PHP开启Xdebug详细配置教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！