ide key 必须唯一且对齐，它是 xdebug 路由调试请求的唯一凭证；错配会导致断点不触发、会话被挤掉、变量窗口空白，需通过运行时动态传入而非 php.ini 硬编码。
多个 IDE 同时监听同一个 Xdebug 配置，断点经常不触发、会话被挤掉、变量窗口空白——根本不是端口没开或扩展没装，而是 IDE Key 没对齐。它不是“可选项”，而是 Xdebug 路由调试请求的唯一凭证。
IDE Key 是什么，为什么必须唯一
IDE Key 是一个纯字符串标识（比如 PHPSTORM、VSCODE_ALICE），Xdebug 用它决定“这个调试请求该交给哪台 IDE”。它不参与 TCP 连接建立，但一旦不匹配，Xdebug 就会静默丢弃整个请求——IDE 完全收不到信号，日志里却可能显示 “Connected to client”，造成严重误判。
- 直连模式下：IDE Key 主要用于触发（如 URL 中
?XDEBUG_SESSION_START=VSCODE），不匹配则不启动调试 - DBGp Proxy 模式下：IDE Key 是强制路由依据，缺失或错配 = 请求被代理直接忽略
- 多开发者共用同一 key（如都设为
PHPSTORM）：Xdebug 只把所有请求发给第一个注册的 IDE，后接入者永远断连
php.ini 中不要硬写 xdebug.idekey
全局写死 xdebug.idekey="PHPSTORM" 是多用户/多项目场景下最常见错误。正确做法是：
- 在 php.ini 中删掉该行，或设为
xdebug.idekey="" - 改由运行时动态传入：通过浏览器插件（Xdebug Helper）设置、URL 参数（
?XDEBUG_SESSION_START=PROJECT_B）、或环境变量（PHP_IDE_CONFIG="ide-key=PROJECT_B"） - VS Code 用户尤其注意：如果 php.ini 里写了 idekey，launch.json 中的
"ideKey"会被忽略
多项目或多 IDE 场景下的 Key 分配规则
每个独立调试上下文必须有专属 key，不能复用，建议按“角色+项目”命名，例如：
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
-
ALICE_API：Alice 调试 API 服务 -
BOB_ADMIN：Bob 调试后台管理模块 -
CI_TEST：CI 环境自动化调试专用（配合XDEBUG_MODE=debug使用）
浏览器插件中每个域名可单独配置 IDE Key；PHP-FPM pool 级别也可通过 php_admin_value[xdebug.idekey] 强制指定，避免混用。
DBGp Proxy 模式下 Key 的注册与验证
启用代理后，IDE Key 必须同时满足三处一致：
- PHP 运行时传入的值（如 cookie
XDEBUG_SESSION_START=ALICE_API） - dbgpProxy 启动时声明的 key（
-k ALICE_API） - IDE 在代理注册界面填写的 key（PhpStorm：Tools → DBGp Proxy → Register IDE；VS Code：launch.json 中
"ideKey": "ALICE_API"）
三者缺一不可。代理日志中若出现 Ignoring connection: IDE key 'XXX' not registered，说明其中某一处不匹配。
