Windows本地调试ThinkPHP插件需三步：一验证调试模式真实生效（php think status + 强制App::debug(true)）；二PhpStorm配置绝对路径映射（项目根目录和vendor单独映射）；三CLI模式调试插件命令（Run → PHP Script，设XDEBUG_CONFIG及首行断点）。
在Windows本地调试ThinkPHP插件时，常遇到断点不命中、路径映射错乱、Xdebug连接成功但变量为空等问题，根源往往不是插件本身，而是IDE、Web服务器与框架三者间的路径解析偏差和调试模式加载时机错位。
确认调试模式已真实生效
ThinkPHP插件（如think-swoole、think-queue）的调试行为严重依赖框架级调试开关。仅在.env中写APP_DEBUG=true并不足够。
第一步：执行命令行验证当前实际生效状态：php think status
第二步：检查输出中app_debug字段是否为true且env_file显示已加载.env。若未加载，说明入口文件public/index.php中调用了Env::load()但路径错误，或.env文件权限被Windows继承策略拦截——此时需右键文件→属性→安全→编辑→赋予IIS_IUSRS或www-data读取权限。
立即学习“PHP免费学习笔记（深入）”；
第三步：强制在public/index.php顶部插入一行：\think\facade\App::debug(true);。这绕过所有配置优先级，确保插件初始化前调试模式已激活。
PhpStorm中配置正确的路径映射
这是Windows本地调试ThinkPHP插件最易失败的环节。Xdebug报错“Cannot find a local copy of the file”本质是IDE把E:\www\project\vendor\topthink\think-queue\src\queue.php识别为E:/www/E:\www\project\vendor\...——路径被重复拼接。
方法一：使用绝对路径映射（推荐）
打开PhpStorm → File → Settings → PHP → Servers，点击+号添加新服务器：
名称填loc.thinkphp，Host填loc.thinkphp.test，Port填80；勾选“Use path mappings”，在下方列表中点击+号；
Local path选中你的整个项目根目录（如E:\www\project），Absolute path on the server填/；
【关键】再单独添加一条映射：Local path指向vendor目录（如E:\www\project\vendor），Absolute path on the server填/vendor。否则插件源码断点永远无法触发。
方法二：关闭自动路径检测
在PhpStorm → Settings → PHP → Debug → Xdebug → “Filter debug connections by IDE key”取消勾选；同时在php.ini中将xdebug.start_with_request = trigger改为yes，避免依赖浏览器插件传递key导致路径识别异常。
启动插件专用调试会话
ThinkPHP插件通常不走HTTP请求生命周期，而是通过命令行启动（如php think queue:work或php think swoole），因此必须用CLI调试模式。
第一步：在PhpStorm中，Run → Edit Configurations → + → PHP Script；
第二步：Script path选think文件（位于项目根目录）；
第三步：Arguments填queue:work --queue default --tries 1（先设tries=1便于快速失败定位）；
第四步：Working directory设为项目根目录；Environment variables中手动添加XDEBUG_CONFIG=idekey=PHPSTORM；
第五步：勾选“Force break at first line when a script is executed”，然后点击Debug按钮。此时控制台会停在think文件第一行，按F8逐过程步入，直到进入插件源码vendor/topthink/think-queue/src/Command/Work.php即可下断点。
