PhpStorm配置Xdebug成功的关键是PHP端配置准确：必须在php.ini中正确设置zend_extension绝对路径、xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host与client_port（如9003），且端口需与PhpStorm Debug设置一致，路径映射须精确对应，触发调试需加?XDEBUG_SESSION_START=PHPSTORM参数。
PhpStorm 能快速配好 Xdebug，但前提是 PHP 端的扩展和配置一步都不能错——90% 的失败不是 PhpStorm 没设对，而是 php.ini 里少了一行 zend_extension，或者端口没对齐、xdebug.mode 写成了 on。
确认 Xdebug 扩展已加载且版本匹配
不看 phpinfo() 就瞎配，等于蒙眼装枪。必须先验证扩展真实存在并被 PHP 认出：
- 在项目根目录（如
public/）放一个info.php，内容只有<?php phpinfo(); ?> - 浏览器访问，右键「查看网页源代码」，全选复制整页 HTML 源码
- 打开 https://www.php.cn/link/1706199530ef96af148faaacf8779264，粘贴源码，点击 Analyse my phpinfo() output
- 它会精确告诉你该下哪个文件，比如
php_xdebug-3.3.1-8.2-vc15-x86_64.dll；Windows 下务必核对VC版本、TS/NTS、位数是否与php -v输出一致 - 下载后放进 PHP 的
ext目录，再运行php -v，输出里必须带with Xdebug v3.3.1字样
php.ini 必须写对的四行核心配置（Xdebug 3.x）
Xdebug 3 彻底废弃 xdebug.remote_* 前缀，混用旧参数会导致静默失效。以下是最小可用配置，直接追加到 php.ini 末尾：
-
zend_extension="D:/phpstudy_pro/Extensions/php/php8.2.12/ext/php_xdebug-3.3.1-8.2-vc15-x86_64.dll"（路径必须是绝对路径，且文件真实存在） -
xdebug.mode=debug（注意：不是on、true或1，必须是字符串debug） -
xdebug.start_with_request=trigger（按需触发，避免所有请求都进调试；设为yes则全自动，慎用） -
xdebug.client_host=127.0.0.1和xdebug.client_port=9003（端口要和 PhpStorm 后面对得上；Docker/WSL 用户这里必须填宿主机 IP，不能写127.0.0.1）
改完 php.ini，重启 Web 服务（Apache/Nginx）或 PHP-FPM 进程，否则配置不生效。
立即学习“PHP免费学习笔记（深入）”；
PhpStorm 中三处关键设置不能漏
PhpStorm 不需要“安装插件”，它靠监听端口捕获 Xdebug 连接。重点就三块：
-
PHP 解释器：Settings → PHP → Interpreter → 点右侧 “+” → 选你的
php.exe（如D:\phpstudy_pro\Extensions\php\php8.2.12\php.exe），右侧应立刻显示Xdebug 3.3.1 -
Debug 端口：Settings → PHP → Debug → Xdebug →
Debug port改成和php.ini里xdebug.client_port一致（默认 9003） -
服务器路径映射（Path Mappings）：Settings → PHP → Servers → 编辑你的本地服务器（如
localhost）→ 勾选Use path mappings→ 左边填项目在 PhpStorm 里的绝对路径（如D:/project/tp6），右边填对应 Web 服务器能访问到的路径（如D:/project/tp6/public）。这步漏了，断点永远不命中
启动调试前必做：浏览器加 XDEBUG_SESSION_START 参数
除非你设了 xdebug.start_with_request=yes，否则必须显式触发。最稳的方式不是装插件，而是手动加参数：
- 在浏览器地址栏当前 URL 后面加上
?XDEBUG_SESSION_START=PHPSTORM（PHPSTORM要和php.ini里xdebug.idekey值一致） - 例如原 URL 是
http://localhost/tp6/index.php，改成http://localhost/tp6/index.php?XDEBUG_SESSION_START=PHPSTORM - 点回车前，确保 PhpStorm 右上角那个电话图标是绿色（已开启监听）；第一次连接会弹窗提示“Accept incoming connection”，点 Accept
- 如果没反应，检查
xdebug.log（可加一行xdebug.log="D:/tmp/xdebug.log"到php.ini），日志里会明确报错是连不上端口、还是路径没映射上
路径映射不对、xdebug.mode 拼错、zend_extension 路径不存在——这三个问题占实际调试失败的 80%，其他都是表象。
