IDEkey必须与php.ini中xdebug.idekey值完全一致(大小写、空格、引号均需匹配),否则断点不触发;PhpStorm中在Settings→PHP→Debug→Xdebug→IDE key处手动填写,推荐统一使用PHPSTORM以确保兼容性。

IDEkey 必须和 php.ini 里 xdebug.idekey 完全一致
PhpStorm 不会自动读取或校验 xdebug.idekey 的值,它只在调试请求到达时,用你手动填入的 IDEkey 去匹配 PHP 进程发来的 XDEBUG_SESSION(或 XDEBUG_SESSION_START)请求头里的 key。哪怕差一个大小写、多一个空格,都会导致断点不触发。
常见错误现象:断点标红了、Debug 监听已开启(绿色电话图标亮着)、浏览器也点了 Debug 模式,但程序就是不停 —— 八成是 IDEkey 对不上。
-
xdebug.idekey在 php.ini 中设为"PHPSTORM",PhpStorm 的 IDEkey 就必须填PHPSTORM(注意全大写、无引号、无空格) - 如果 php.ini 里写的是
xdebug.idekey = "phpstorm",那 PhpStorm 里就得填phpstorm(小写) - Xdebug 3 默认不强制要求
idekey,但 PhpStorm 仍依赖它做路由;不配或配错,xdebug.mode=debug也会静默失败
PhpStorm 里 IDEkey 的填写位置(Xdebug 2 和 Xdebug 3 一样)
路径是:Settings → PHP → Debug → Xdebug → IDE key。不是在 Server 配置页,也不是在 Edit Configurations 里。
这个字段没有默认值,首次打开是空的,必须手动输入。输完后不用重启 PhpStorm,但要确保后续所有调试请求都携带匹配的 key(比如通过浏览器插件或 URL 参数 ?XDEBUG_SESSION_START=PHPSTORM)。
立即学习“PHP免费学习笔记(深入)”;
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
- 不要勾选 “Filter debug connections by IDE key” —— 这个选项会拦截所有没带 key 的请求,对 CLI 调试或某些代理场景反而坏事
- 如果你用的是 Xdebug Helper 浏览器插件,它的 “IDE Key” 设置项也得同步改,否则插件发不出正确 header
- CLI 调试(如
php -dxdebug.mode=debug script.php)默认不带 key,需额外加-dxdebug.idekey=PHPSTORM
为什么推荐固定用 PHPSTORM 而不是自定义值
因为它是 Xdebug 官方文档和 PhpStorm 内置模板默认采用的值,兼容性最稳。自定义 key 容易引发两个隐藏问题:
- 某些旧版 Xdebug(尤其是 2.x)对 key 长度或字符有隐式限制,用中文、下划线或过长字符串可能被截断或忽略
- 部分 Docker 或远程部署环境会预设
XDEBUG_CONFIG="idekey=PHPSTORM",若本地改了 key,又没同步改环境变量,就断连 - 团队协作时,不同人填不同 key,会导致同一套
php.ini配置在别人机器上直接失效
所以除非有明确理由(比如同时连多个 IDE),否则就用 PHPSTORM,写死在 php.ini 和 PhpStorm 里,省去排查成本。
验证 IDEkey 是否生效的最快方式
不用等断点,直接看 Xdebug 日志或 PhpStorm 的 Debug 控制台输出。启用 xdebug.log 后(如 xdebug.log="/tmp/xdebug.log"),启动一次页面请求,然后 grep 关键字:
grep "idekey" /tmp/xdebug.log
如果看到类似 [Step 1] -> idekey="PHPSTORM",说明 PHP 进程收到了正确的 key;如果显示 idekey="" 或根本没这行,说明浏览器没发、插件没启、或 URL 参数拼错了。
真正容易被忽略的点:Xdebug 3 默认关闭 xdebug.log,且日志路径必须存在且可写;而 PhpStorm 的 Debug 控制台只显示连接建立后的通信,不报“key 不匹配”这种前置错误 —— 所以日志才是唯一可信依据。

















