能跑断点不代表能单步排查逻辑漏洞，关键在xdebug.mode=debug必须生效、xdebug.client_port与PhpStorm监听端口必须完全一致（默认9003）、IDE Key必须双向匹配为PHPSTORM，三者缺一即F7/F8失效。
能跑断点，不代表能单步排查逻辑漏洞——关键在 xdebug.mode=debug 必须生效、xdebug.client_port 和 PHPStorm 监听端口必须完全一致、IDE Key 必须双向匹配，三者任一缺失，F7/F8 就只是“假装在调试”。
确认 Xdebug 已加载且 mode 含 debug
别信 phpinfo() 页面上“Xdebug”标题栏存在就万事大吉。右键查看源码，全选复制整页内容，粘贴到 xdebug.org/wizard，它会告诉你该下哪个 exact 版本的 php_xdebug-*.dll 或 xdebug.so。然后执行：
-
php -v输出里必须带xdebug字样（不是Xdebug大写开头那种假象） -
php --ri xdebug查看输出，重点核对：
—xdebug.mode值是否包含debug（如debug,develop可以，off或空值不行）
—xdebug.client_port是否为9003（Xdebug 3.x 默认值，不是 9000）
—xdebug.start_with_request是yes还是trigger，决定你是否必须加 URL 参数 - Windows 下
zend_extension路径必须是绝对路径，且文件真实存在，比如："D:/phpstudy_pro/Extensions/php/php7.4.33/ext/php_xdebug-3.1.5-7.4-vc15-x86_64.dll"
PHPStorm 端监听配置必须手动对齐
PHPStorm 不会读取 php.ini，它只认自己设置的端口和开关。进 Settings → PHP → Debug，检查以下三项：
-
Debug port必须和xdebug.client_port完全一致（默认都是9003，但有人手抖改成9000或9002） -
Can accept external connections必须勾选，否则连接直接被丢弃 -
IDE key必须设为PHPSTORM（大小写敏感，不能是phpstorm或PhpStorm）
另：如果项目跑在 Docker、WSL 或远程服务器上，Settings → PHP → Servers 里必须添加对应 host，并启用 Use path mappings，把容器内路径（如 /var/www/html）映射到本地项目路径（如 D:\project），否则断点命中但不暂停。
立即学习“PHP免费学习笔记（深入）”；
触发调试前先验证 IDE Key 传递是否成功
断点不响，90% 是请求压根没带调试指令。Xdebug 不会自动监听所有请求，必须显式激活：
- 用
Xdebug Helper浏览器插件（Chrome/Firefox），点击图标 → 选Debug，它会在 URL 后自动加?XDEBUG_SESSION_START=PHPSTORM - 确保插件设置里的 IDE Key 是
PHPSTORM，且和 PHPStorm 中Settings → PHP → Debug → Xdebug → IDE key一致 - 命令行调试不要依赖
php -dxdebug.start_with_request=yes script.php，部分 PHP 版本不支持；改用：XDEBUG_CONFIG="idekey=PHPSTORM" php script.php - 若用
xdebug.start_with_request=trigger，就必须带参数；若设为yes，则所有 HTTP 请求都会尝试连接，但依然要靠 IDE Key 匹配才能建立会话
单步执行时变量看不到？先看 Frames 和 Path Mapping
F7（Step Into）、F8（Step Over）能走，但 Variables 面板为空或显示 undefined，大概率是路径映射没对：
- 打开 Debug 工具窗口 → 左上角
Frames面板，看当前堆栈帧里显示的文件路径是本地路径还是远程/容器路径（如/app/Controller/UserController.php） - 如果是后者，说明
path mappings没生效，PHPStorm 找不到对应本地文件，自然无法关联变量作用域 - 检查
Settings → PHP → Servers → [你的 server] → Path mappings，左边填远程路径（如/app），右边填本地绝对路径（如D:\project），必须一一对应 - ThinkPHP/Laravel 等框架入口常在
public/index.php，但实际逻辑在app/下，映射必须覆盖整个应用目录，不能只映射 public
路径映射错一个字符、少一个斜杠，Variables 面板就成摆设——这不是功能问题，是调试会话根本没把上下文正确传过来。
