xdebug 3 配置必须使用 xdebug.client_ 前缀（如 client_host、clientport）替代已废弃的 xdebug.remote，且必须设置 xdebug.mode=debug 并确保 client_port=9003 与 ide 监听端口一致，否则调试完全不生效。

Xdebug 3 的配置项命名和逻辑已彻底重构，直接套用 Xdebug 2 的 xdebug.remote_* 参数会导致调试完全不生效——这是最常被忽略、也最容易卡住人的点。

区分 Xdebug 2 和 Xdebug 3 的核心配置前缀

旧版（Xdebug 2）用 xdebug.remote_host、xdebug.remote_port；新版（Xdebug 3）全部改为 xdebug.client_host、xdebug.client_port。二者不能混用，PHP 启动时若检测到冲突参数会静默忽略部分配置。

常见错误现象：

• PHPInfo 显示 Xdebug 已加载，但 PhpStorm 完全收不到连接
• 断点灰色不可用，或点击「Start Listening」后无任何日志输出
• php -i | grep xdebug 输出中看不到 client_host 或 mode 相关字段

实操建议：

• 先运行 php -v 确认 Xdebug 版本（输出含 Xdebug v3.x.x 即为新版）
• 新版必须设置 xdebug.mode=debug，否则所有调试功能默认关闭
• 不要在 php.ini 中同时存在 xdebug.remote_host 和 xdebug.client_host

xdebug.mode 控制哪些功能实际启用

它不是开关，而是功能组合开关。值为逗号分隔的字符串，决定 Xdebug 启动哪些子系统。

常用组合：

• xdebug.mode=debug：仅启用远程调试（最常用）
• xdebug.mode=debug,develop：调试 + 增强错误提示（如带变量值的堆栈）
• xdebug.mode=profile：启用性能分析器（生成 cachegrind 文件）
• xdebug.mode=off：彻底禁用（比注释掉扩展更干净）

注意：xdebug.mode=debug 不等于自动监听——还需配合 xdebug.start_with_request 或请求触发机制。

btpanel phpsite 宝塔面板PHP网站

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

下载

xdebug.start_with_request 决定调试何时启动

这个参数控制“是否对每个 HTTP 请求都尝试建立调试连接”，直接影响开发体验和性能开销。

可选值及影响：

• default：只在收到 XDEBUG_SESSION cookie 或 GET/POST 参数时启动（推荐）
• yes：每个请求都强制发起调试握手（本地开发可接受，线上绝对禁用）
• no：完全不自动启动，需手动调用 xdebug_break()

典型场景：

• 浏览器插件（如 Xdebug Helper）点「Debug」时，自动注入 XDEBUG_SESSION=PHPSTORM
• Postman/Apifox 测试接口时，在 Headers 中加 XDEBUG_SESSION: PHPSTORM
• Docker 环境下，xdebug.client_host=host.docker.internal 才能正确路由到宿主机 IDE

端口、日志与 IDE 关联的关键细节

调试失败多数不是因为配错，而是没对齐三个端点：

• PHP 进程发往哪个 IP 和端口？→ xdebug.client_host + xdebug.client_port
• PhpStorm 监听哪个端口？→ Settings → PHP → Debug → Xdebug → Debug port
• 浏览器/请求是否携带有效触发标识？→ XDEBUG_SESSION=PHPSTORM 或 cookie

容易踩的坑：

• xdebug.client_port 默认是 9003（Xdebug 3），不是旧版的 9000；若 PhpStorm 仍设为 9000，连接必然失败
• 开启 xdebug.log 路径需确保 PHP 进程有写权限，否则日志静默丢失，排查无从下手
• xdebug.idekey 在 Xdebug 3 中已废弃，xdebug.start_with_request=default 下无需设置

真正关键的是三者一致：PHP 认为要连的地址、IDE 实际监听的地址、请求携带的上下文标识，缺一不可。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！