断点不命中首要确认Xdebug是否加载：通过phpinfo()查看是否存在Xdebug模块，若无则检查zend_extension路径、PHP/Xdebug版本兼容性及php.ini是否为Web服务器实际加载的配置文件。
断点不命中，八成不是 PhpStorm 没设对，而是 Xdebug 根本没连上来——先确认连接通不通，再查断点落不落。
phpinfo() 里看不到 Xdebug 模块？立刻停手检查扩展加载
这是最基础也最容易被跳过的一步。很多人改了 php.ini 就去重启 Apache，却没验证 Xdebug 是否真被 PHP 加载。
- 在 ThinkPHP 的
public/目录下新建info.php，内容只有一行：<?php phpinfo(); ?> - 用浏览器访问
http://localhost/tp5/public/info.php（端口按你实际配的填），右键「查看网页源代码」，全选复制整页 HTML 源码 - 打开 xdebug.org/wizard，粘贴源码，它会明确告诉你该下哪个
php_xdebug-*.dll或xdebug.so文件，连 VC 版本、TS/NTS、位数都判定了 - 下载后放进 PHP 的
ext目录（如D:\phpstudy_pro\Extensions\php\php8.3.12\ext\），路径必须是绝对路径且文件真实存在 - 运行
php -v，输出里必须带xdebug字样；若没有，说明zend_extension路径写错、文件名不对、或 PHP 版本与 Xdebug 不兼容（比如给 PHP 8.3 装了标称支持 PHP 7.4 的包）
Xdebug 3 配置项写错一个就静默失效？重点核对这四个参数
Xdebug 3 彻底废弃了 xdebug.remote_* 系列旧参数，混用会导致整个调试模块不响应，且不报错。
-
xdebug.mode=debug：必须写成debug，不能写on、true、1或留空；想同时启用开发辅助功能可写xdebug.mode=develop,debug -
xdebug.start_with_request=trigger：推荐设为trigger，靠XDEBUG_SESSION_START=PHPSTORM触发，避免所有请求都进调试拖慢响应；设yes会强制每请求都调试，仅调试 CLI 脚本时考虑 -
xdebug.client_host=127.0.0.1：Windows 用户务必填127.0.0.1，别写localhost，避免 hosts 解析延迟导致超时；Docker/WSL 环境则必须填宿主机真实 IP（如192.168.42.1），不能用127.0.0.1 -
xdebug.client_port=9003：Xdebug 3 默认端口是9003，不是旧版的9000；PhpStorm 中的PHP → Debug → Debug Port必须严格一致
断点能连上但总提示“Cannot find a local copy of the file”？路径映射错在 Windows 反斜杠
这是 Windows + Wamp/XAMPP + Xdebug 3 下最高频的断点失败原因：远程路径（如 E:\www\public\index.php）和本地路径（如 E:/www/public/index.php）因反斜杠转义或大小写不一致，被 PhpStorm 错误拼接成 E:/www/E:\www\public\index.php。
立即学习“PHP免费学习笔记（深入）”；
- 进入
Run → Edit Configurations… → PHP Web Page，点击右侧Server configuration下的…按钮 - 在
Path mappings表格中，File path on server填服务器上看到的完整路径（如E:\www\public\index.php），Project files填你本地项目根目录（如E:/www） - 关键：两个路径都统一用正斜杠
/，且结尾不加斜杠；例如服务器路径写E:/www/public/index.php，映射到本地E:/www，这样 PhpStorm 才能正确截掉前缀 - 如果项目不在默认
www目录下（如放在E:\project\shop），映射必须精确到该目录层级，不能笼统映射为/
Chrome 插件点了“Debug”还是不进断点？检查 cookie 和 IDE Key 是否对得上
Xdebug Helper 插件本质是往请求头里加 XDEBUG_SESSION_START=PHPSTORM，并设一个同名 cookie。一旦 cookie 过期或 IDE Key 不匹配，调试请求就被忽略。
- 打开 Chrome 开发者工具 → Application → Cookies，确认域名下存在名为
XDEBUG_SESSION的 cookie，值为PHPSTORM - 检查
php.ini中是否设置了xdebug.idekey=PHPSTORM；若设成其他值（如myide），插件就必须同步切换 IDE Key - 插件图标右键 → Options → IDE Key，必须与
php.ini中的xdebug.idekey完全一致（区分大小写） - 如果刚改过配置，清空浏览器所有 cookies 再试；或者直接在 URL 后手动加参数触发：
?XDEBUG_SESSION_START=PHPSTORM
真正卡住的地方，往往不是“怎么配”，而是“配给谁”——CLI 的 php.ini 和 Web 服务（Apache/Nginx+PHP-FPM）用的 php.ini 是两份独立文件，改错一个就白忙活。每次验证前，先用 php --ini 和 phpinfo() 确认你正在操作的是那个“真正在跑请求”的配置文件。
