ThinkPHP项目Xdebug调试核心三步：扩展安装匹配、php.ini配置Xdebug 3.x参数（如xdebug.mode=debug、xdebug.client_port=9003）、PhpStorm精准设置path mappings；任一缺失均导致断点失效。
ThinkPHP项目用Xdebug调试，核心就三件事：扩展得装对、php.ini参数得写准、PhpStorm路径映射得配好。漏掉任何一环，断点都停不住。
确认Xdebug扩展已正确加载
别凭感觉——运行php -v，输出里必须出现xdebug字样；再建一个info.php（内容仅<?php phpinfo(); ?>），用浏览器打开，全选页面源码，粘贴到xdebug.org/wizard。它会告诉你该下哪个.dll或.so文件，连VC版本、TS/NTS、位数都给你判清楚。Windows下路径务必用绝对路径，比如：zend_extension="D:/phpstudy_pro/Extensions/php/php7.4.33/ext/php_xdebug-3.1.5-7.4-vc15-x86_64.dll"
下载后放对位置，重启PHP服务，再查php -v和phpinfo()双验证。
php.ini只留Xdebug 3.x必需参数
Xdebug 3.x已彻底废弃所有xdebug.remote_*旧参数，混用就会静默失效。在php.ini末尾加这几行就够了：
zend_extension=你的xdebug绝对路径-
xdebug.mode=debug（注意不是on或1） -
xdebug.start_with_request=trigger（不自动启，靠插件或URL参数触发） -
xdebug.client_host=127.0.0.1（Windows推荐，比localhost稳） -
xdebug.client_port=9003（PhpStorm默认端口，保持一致） -
xdebug.idekey=PHPSTORM（浏览器插件和IDE里都要匹配）
Docker或WSL环境要把client_host换成宿主机真实IP，不能写127.0.0.1。
立即学习“PHP免费学习笔记（深入）”；
PhpStorm路径映射必须精准对应
这是Windows本地最常卡住的点：断点设了，Xdebug也连上了，但提示“Cannot find a local copy of the file”。根本原因是路径拼接错乱，比如显示E:/www/E:\www\public\index.php——明显重复了。
解决方法是手动配置Path Mapping：
- PhpStorm → Settings → PHP → Servers，新增或编辑你的服务器（如
loc.rule.com） - Host填你虚拟主机名（如
loc.rule.com），Port填80或实际端口 - 关键一步：在“Debugger”区域勾选“Use path mappings”，点击“+”添加映射
- Remote path填
/（代表Web根目录，即public/） - Local path选中你项目的
public目录（如E:/www/wwwroot/php/thinkphp/shop_order_rule_design/public）
确保Apache虚拟主机DocumentRoot指向public/，hosts里有对应条目，这样请求路径和本地路径才能一对一映射上。
浏览器触发与断点实操
装Chrome插件“Xdebug Helper”，右键图标选“Debug”，它会在请求头里自动加XDEBUG_SESSION_START=PHPSTORM。配合xdebug.start_with_request=trigger，就能精准激活单次调试。
在PhpStorm里：
- 顶部菜单Run → Start Listening for PHP Debug Connections（小虫子图标亮起）
- 在代码里点行号左侧设断点（红点出现）
- 访问
http://loc.rule.com，页面会暂停，焦点切到PhpStorm，变量、堆栈、监视窗口全可查看
不复杂但容易忽略。
