PHP Xdebug 3断点调试配置方法

Xdebug 3 的断点调试与旧版有根本性差异：它默认完全禁用所有功能，必须显式配置 `xdebug.mode=debug`（而非无效的 `on`）和严格匹配 IDE 端口的 `xdebug.client_port`（默认9003，非9000），同时需通过浏览器插件或 `?XDEBUG_SESSION_START=PHPSTORM` 主动激活调试会话，缺一不可；本地开发还需注意 `xdebug.client_host` 显式设为 `127.0.0.1`、正确加载对应 PHP 版本的 zend_extension，并开启 `xdebug.log` 快速定位连接失败等常见问题——这些看似细微的配置差异，正是无数开发者反复踩坑、断点始终不触发的真正原因。

Xdebug 3 的 xdebug.mode 和 xdebug.client_port 必须显式配置，否则断点不会触发 —— 这是和 Xdebug 2 最关键的区别，也是本地调试失败最常见的原因。

为什么 xdebug.mode 不设就进不了断点

Xdebug 3 默认关闭所有调试功能，xdebug.mode 是总开关，它不是布尔值，而是一个以逗号分隔的模式列表。只设 zend_extension 或 xdebug.idekey 完全无效。

• xdebug.mode=debug：仅启用远程调试（对应旧版 xdebug.remote_enable=1）
• xdebug.mode=debug,develop：同时启用调试 + 开发辅助（如 xdebug_info() 函数可用）
• xdebug.mode=off：彻底禁用（即使其他配置都对，也绝不会连接 PhpStorm）
• 不要用 xdebug.mode=on —— 该值在 Xdebug 3 中不存在，会被忽略

xdebug.client_port 必须和 PhpStorm 的 Debug Port 严格一致

旧版用 xdebug.remote_port，Xdebug 3 改为 xdebug.client_port，且默认值从 9000 变为 9003。如果你没改 PhpStorm 设置，它仍默认监听 9000，两端端口不匹配 = 连接直接被拒绝。

• PhpStorm 中设置路径：Settings > PHP > Debug > Xdebug > Debug port
• 若保持 PhpStorm 默认（9000），则 php.ini 中必须写：xdebug.client_port=9000
• 若改 PhpStorm 为 9003，php.ini 中也要同步写 xdebug.client_port=9003
• Windows 下常见冲突：Apache、Docker、WSL2 都可能占着 9000；建议统一用 9003 避免排查

完整最小可用配置示例（PHP 8.1 + Windows + PhpStorm）

以下为 php.ini 中 Xdebug 3 段落的最小必要项，删掉任何一行都可能导致断点失效：

zend_extension=php_xdebug-3.1.5-8.1-vc15-x86_64.dll
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.log=C:/tmp/xdebug.log

• xdebug.client_host 在本地开发时不能省略，尤其 WSL2 或 Docker 环境下必须显式指定，不能依赖 localhost 解析
• xdebug.log 强烈建议开启，调试失败时第一眼就看这个日志里有没有 Connection to client failed 或 Failed to send breakpoint
• 确认 zend_extension 路径中的 DLL 文件真实存在，且文件名与 PHP 版本、VC 编译器、位数完全匹配（查 phpinfo() 的 Compiler 和 Architecture）

最容易被忽略的是：Xdebug 3 不再自动读取 $_SERVER['HTTP_XDEBUG_SESSION_START'] 或 cookie 触发调试，必须配合浏览器插件（如 Xdebug Helper）手动开启会话，或在 URL 后加 ?XDEBUG_SESSION_START=PHPSTORM —— 否则 xdebug.mode=debug 也白设。

今天关于《PHP Xdebug 3断点调试配置方法》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！