xdebug 3.x 单步调试需同时满足：xdebug.mode=debug 生效、xdebug.client_port 与 phpstorm 监听端口完全一致、ide key 双向设为 phpstorm（大小写敏感），缺一则 f7/f8 失效。
能设断点不等于能单步调试——Xdebug 3.x 必须同时满足三个硬性条件：xdebug.mode=debug 生效、xdebug.client_port 与 PhpStorm 监听端口完全一致、IDE key 双向设为 PHPSTORM（大小写敏感）。缺一即 F7/F8 失效，只停在第一行或根本不暂停。
确认 xdebug.mode=debug 是否真正生效
别信 phpinfo() 页面上那个“Xdebug”标题栏。很多环境加载了 Xdebug 扩展但 mode 是 off 或仅含 develop，debug 没开就无法建立调试会话。
- 执行
php --ri xdebug，检查输出中xdebug.mode的值是否包含debug（例如debug,develop可以，off、develop单独不行） - 若用 Xdebug 2.x，请确认
xdebug.remote_enable=1，而非只配了remote_host等参数 - Windows 下
zend_extension路径必须是绝对路径，且文件真实存在；路径中反斜杠要双写或改用正斜杠，否则扩展加载失败但无报错 - 重启 PHP 服务（如 Apache/Nginx/PHP-FPM）后，再运行
php -v，输出里必须出现with Xdebug v3.x.x（注意是小写 xdebug 开头，大写 Xdebug 开头可能是假加载）
PhpStorm 监听端口必须和 xdebug.client_port 完全对齐
PhpStorm 不读取 php.ini，它只认自己 Settings → PHP → Debug 里的配置。哪怕 xdebug.client_port=9003 写对了，PhpStorm 里 Debug port 设成 9000 或 9002，连接就会静默丢弃。
- 默认值不是保险值：Xdebug 3.x 默认
xdebug.client_port=9003，但很多人复制旧教程仍设9000，结果两端不匹配 - 务必勾选
Can accept external connections，否则本地回环（127.0.0.1）请求也会被拒绝 - 如果项目跑在 Docker 或 WSL 中，
xdebug.client_host不能写127.0.0.1，得填宿主机网关 IP（如host.docker.internal或10.0.2.2），否则连接超时
IDE key 必须双向设为 PHPSTORM（大小写敏感）
这个值是 Xdebug 和 PhpStorm 之间握手的“暗号”，错一个字母或大小写都不行。浏览器插件传的是 PHPSTORM，但 PhpStorm 里设成 phpstorm 或 PhpStorm，请求就进不来。
- PhpStorm 设置位置：Settings → PHP → Debug → Xdebug →
IDE key，必须填PHPSTORM - 浏览器插件（如 Xdebug Helper）设置页里，IDE Key 字段也必须填
PHPSTORM，且 Domain filter 要覆盖当前访问域名（如localhost、dev.test） - URL 触发方式（手动加参数）必须用
?XDEBUG_SESSION_START=PHPSTORM，不能写成XDEBUG_SESSION或漏掉START - 命令行调试慎用
php -dxdebug.start_with_request=yes，部分 PHP 版本不识别；推荐改用export XDEBUG_CONFIG="idekey=PHPSTORM"+php script.php
路径映射没配对会导致断点命中但不暂停
尤其在 Docker、WSL、远程服务器场景下，Xdebug 告诉 PhpStorm “我在 /var/www/html/index.php 第 42 行”，但 PhpStorm 打开的是 D:\project\index.php —— 路径对不上，断点就只是个红点，不会中断执行。
- Settings → PHP → Servers → 添加对应 host（如
dev.test），启用Use path mappings - 左边填容器/远程路径（如
/var/www/html），右边填本地项目根目录（如D:\project），必须一一对应 - 映射关系必须精确到目录层级，多一个
/或少一个都可能失效；建议用 PhpStorm 自动检测功能辅助校验 - 如果用 PHP 内置服务器（
php -S），也要在 Servers 里添加对应 host，并设好映射，否则 localhost:8000 请求无法关联到本地文件
最常被忽略的是三者协同验证：改完 php.ini 后，必须同时检查 php --ri xdebug 输出、PhpStorm Debug 设置页、浏览器插件 IDE key 三处是否全部为 PHPSTORM 且端口一致。任意一处脱节，调试就退化成“看得到断点，按不了 F7”。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
