phpstorm如何配置Xdebug3.0版本（新版调试协议）-phpstorm-PHP中文网

必须用xdebug.mode=debug，xdebug 3已废弃xdebug.remote_enable=1；若断点无反应，八成是该参数未设对或php.ini路径错误，且需确保zend_extension路径准确、端口与ide一致、pathmappings映射正确。

phpstorm如何配置xdebug3.0版本（新版调试协议）

断点点了没反应？八成是 xdebug.mode 没设对。Xdebug 3 彻底废弃了 xdebug.remote_enable=1 这类旧参数，写了也白写，还会干扰加载。必须显式启用调试模式：

xdebug.mode=debug 是唯一触发断点的开关（可加 develop 或 profile，但 debug 缺不得）
如果 phpinfo() 页面里搜不到 xdebug.mode 这一行，说明 Xdebug 根本没加载，或版本低于 3.0
CLI 和 Web SAPI 加载的 php.ini 常不是同一份：PHPStorm 的 CLI 解释器配置页里看 Configuration file 路径；浏览器访问 phpinfo() 看 Loaded Configuration File —— 两者必须一致，否则断点只在终端或只在浏览器生效

zend_extension 指向的 DLL 或 SO 文件路径错一个字符，Xdebug 就静默失败。更隐蔽的是：Zend Debugger、Zend Optimizer 这类扩展会直接拦截 Xdebug 启动。

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

Windows 下路径示例：zend_extension=C:\phpenv\versions\8.2.12\ext\php_xdebug-3.3.1-8.2-vs17-x86_64.dll（注意 .dll 后缀和完整文件名）
Linux/macOS 下路径示例：zend_extension=/usr/lib/php/20220829/xdebug.so（用 php -i | grep extension_dir 确认目录）
删掉或注释掉所有 zend_extension=<path_to_zend_debugger></path_to_zend_debugger> 和 zend_extension=<path_to_zend_optimizer></path_to_zend_optimizer> 行
改完后重启 Web 服务（Apache/Nginx）和 PHP-FPM（如用），仅重启 PHPStorm 不起作用

PHPStorm 点「Start Listening」没反应？不是按钮坏了，是连接被拦在半路。Xdebug 3 默认主动连回 IDE，不是 IDE 被动等连接。

xdebug.client_port=9003（Xdebug 3 默认值），必须和 PHPStorm 设置中 Settings > Languages & Frameworks > PHP > Debug > Xdebug > Debug port 完全一致
xdebug.client_host=127.0.0.1 仅适用于本地开发；Docker 容器内 PHP 需改成 host.docker.internal（macOS/Windows）或宿主机真实 IP（Linux）
xdebug.idekey=PHPSTORM 必须和 PHPStorm 的 Settings > PHP > Debug > DBGp Proxy > IDE key 完全一致（区分大小写）；不填也可，但填了就必须对上
防火墙可能拦截 9003 端口入站连接，临时关闭测试：sudo ufw disable（Ubuntu）或检查 Windows 入站规则

断点命中但变量全空、堆栈显示 ???、跳转到错误文件？大概率是服务器路径没“翻译”成你本地路径。

Xdebug 发送的是服务器上的绝对路径，比如 /var/www/html/index.php；PHPStorm 必须把它映射到你本地打开的路径，比如 /Users/me/project/index.php
在 PHPStorm 的 Settings > Languages & Frameworks > PHP > Servers 里添加对应域名（如 localhost），然后点击右侧 ... 配置 Path mappings
左侧填服务器路径（/var/www/html），右侧填本地路径（/Users/me/project）——方向反了就找不到文件
若用 phpEnv 或 WAMP，路径通常是 C:\phpstudy\WWW 映射到你本地项目目录