Xdebug 3 不兼容 Xdebug 2 参数，必须删除所有 remote_* 类配置项，仅用 xdebug.mode 控制功能，配对更新 client_host/client_port，并设置 xdebug.start_with_request=yes 或 URL 触发调试。

直接改配置文件会失败——Xdebug 3 不兼容 Xdebug 2 的参数名，保留 xdebug.remote_enable、xdebug.remote_host 这类旧参数会导致 PHP 启动时静默忽略 Xdebug，或报 Unknown configuration setting 警告。

删掉所有 Xdebug 2 的旧参数

PHP 启动后看不到 Xdebug 模块，或者 php --version 不显示 Xdebug，大概率是 php.ini 里混着 v2 参数。Xdebug 3 完全废弃了以下配置项，必须全部删除或注释：

• xdebug.remote_enable
• xdebug.remote_host / xdebug.remote_port
• xdebug.remote_autostart
• xdebug.remote_handler
• xdebug.remote_connect_back
• xdebug.remote_mode

哪怕只留一行，Xdebug 3 也可能加载失败。别心存侥幸——它不会“向下兼容”，只会跳过或报错。

只用 xdebug.mode 控制功能开关

Xdebug 2 靠一堆开关控制行为，Xdebug 3 统一收口到 xdebug.mode，值用逗号分隔。常见组合：

立即学习“PHP免费学习笔记（深入）”；

btpanel phpsite 宝塔面板PHP网站

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

下载

• 仅断点调试：xdebug.mode=debug
• 调试 + 更好的 var_dump：xdebug.mode=debug,develop
• 调试 + 性能分析：xdebug.mode=debug,profile
• 调试 + 跟踪执行流：xdebug.mode=debug,trace

注意：xdebug.mode 必须显式包含 debug，否则 PhpStorm 根本收不到断点请求；只写 develop 不会启用调试器。

端口和主机必须配对更新

Xdebug 2 的 xdebug.remote_port=9000 和 xdebug.remote_host=127.0.0.1 在 v3 中已失效，必须换成：

• xdebug.client_port=9003（默认值，可改但需同步 PhpStorm）
• xdebug.client_host=127.0.0.1 或 localhost（二者不等价，推荐用 127.0.0.1 避免 DNS 解析问题）

如果本地 PHP-FPM 占用了 9000 端口（常见于 macOS/Linux），xdebug.client_port 改成 9003 是安全选择，但务必同步修改 PhpStorm → Settings → PHP → Debug → Xdebug → Debug port。

验证是否真生效，别信 phpinfo 页面

phpinfo() 显示 Xdebug 模块存在 ≠ 调试器就通了。真正有效的验证方式只有两个：

• 命令行执行 php -v，输出中必须带 with Xdebug v3.x.x
• 在 PhpStorm 中点击 Validate（Settings → PHP → Debug → Validate），填入一个能访问的 URL（如 http://localhost/test.php），它会自动发起带 XDEBUG_SESSION_START 的请求并等待响应

最容易被忽略的是：Xdebug 3 默认不自动启动调试会话。如果你没在 URL 加 ?XDEBUG_SESSION_START=PHPSTORM，也没设 xdebug.start_with_request=yes，断点根本不会触发——这个参数不是可选，而是调试可用的前提。