Xdebug 3 + xdebug.mode=debug + 显式指定xdebug.client_host + PHPSTORM为idekey是2026年最稳定可落地的配置基线;必须通过xdebug.org/wizard校验环境并严格匹配TS/NTS与位数,仅保留zend_extension、xdebug.mode等5项必要配置,PhpStorm需对齐client_port和idekey,且每次修改php.ini后必须重启PHP或Web服务器。

直接说结论:Xdebug 3 + xdebug.mode=debug + xdebug.client_host 显式指定 + PHPSTORM 作为 idekey,是当前(2026年)最稳定、可复现、适合团队落地的配置基线。
确认 Xdebug 版本与 PHP 环境严格匹配
不靠“猜”或“复制旧配置”,必须走 https://xdebug.org/wizard 流程:
- 在目标环境运行
phpinfo(),右键 → “查看页面源代码”,全选复制(不是浏览器渲染后的文本) - 粘贴到 wizard 页面,点击
Analyse my phpinfo() output - 只下载它推荐的
.dll(Windows)或.so(Linux/macOS)文件,路径和zend_extension值必须完全一致 - 常见错误:
PHP Warning: Xdebug: Unable to register functions, invalid function name or format—— 90% 是 TS/NTS 或位数(32/64)不匹配导致
php.ini 中只保留最小必要配置项
Xdebug 3 的配置大幅精简,xdebug.remote_* 全部废弃,继续写会静默失效。团队应统一禁用以下旧参数:
-
xdebug.remote_enable、xdebug.remote_host、xdebug.remote_port、xdebug.remote_handler -
xdebug.remote_autostart(改用xdebug.start_with_request) - 只保留且明确赋值:
zend_extension、xdebug.mode、xdebug.client_host、xdebug.client_port、xdebug.idekey - 示例(Xdebug 3.3+):
[xdebug] zend_extension = "/usr/lib/php/20230831/xdebug.so" xdebug.mode = debug xdebug.start_with_request = default xdebug.client_host = 127.0.0.1 xdebug.client_port = 9003 xdebug.idekey = PHPSTORM
PhpStorm 端必须对齐 client_port 和 idekey
IDE 设置错一个字符就会断连,团队需强制约定:
立即学习“PHP免费学习笔记(深入)”;
- 进入
Settings → PHP → Debug,把Debug port改为和php.ini中xdebug.client_port完全一致(默认 9003,不是 9000) -
Settings → PHP → Servers中,每个 server 的Debugger必须选Xdebug,且IDE key字段填PHPSTORM(大小写敏感,不能是phpstorm或空) - 禁用
Use path mappings—— 这个勾选项只在远程调试(如 Docker、Vagrant)时才启用;本地开发时勾选会导致断点不命中 - 验证方式:启动监听(绿色甲壳虫),访问带
?XDEBUG_SESSION_START=PHPSTORM的 URL,看 PhpStorm 是否弹出 “Incoming Connection” 对话框
避免多人协作时的端口与 idekey 冲突
团队共用一台开发机或使用共享 Vagrant 环境时,容易踩坑:
- 不要用
xdebug.remote_connect_back=1(Xdebug 2)或xdebug.discover_client_host=1(Xdebug 3)—— 它依赖 HTTP 请求头中的X-Forwarded-For,Nginx/Apache 配置稍有偏差就失败 - 所有成员统一用
xdebug.client_host=127.0.0.1,不写localhost(某些系统 DNS 解析慢会导致超时) -
xdebug.idekey统一设为PHPSTORM,而非个人随意命名(否则浏览器插件或 curl 调试命令要同步改) - 若真需多用户并行调试(如 pair programming),改用
xdebug.client_host指向具体 IP,并确保防火墙放行xdebug.client_port
最常被忽略的一点:每次改完 php.ini,必须重启 PHP-FPM 或 Apache/Nginx 进程,仅刷新网页或重启 PhpStorm 无效。团队配置文档里建议加一句「执行 sudo systemctl restart php*-fpm 或 httpd」—— 这个动作比写十行注释都管用。


















