如何配置PHP Xdebug 3进行断点调试_修改xdebug.mode与client

xdebug 3 必须显式配置 xdebug.mode=debug 和 xdebug.client_port=9003（与 ide 端口一致），否则断点不触发；默认关闭所有功能，且不再自动识别调试请求，需配合 xdebug_session_start 参数或浏览器插件激活会话。

如何配置php xdebug 3进行断点调试_修改xdebug.mode与client_port

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，两端端口不匹配 = 连接直接被拒绝。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

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 也白设。