ThinkPHP中间件断点跳过因Xdebug未正确挂载或路径映射错位，需在public/index.php首行设断点验证连通性，并在Route::dispatch()、Pipeline::then()等枢纽处手动加断点。
为什么ThinkPHP中间件断点总跳过
因为 PhpStorm 默认只监听入口文件（如 public/index.php）的初始请求，而中间件逻辑大多在 think\Pipeline::then()、think\Middleware::dispatch() 这类反射调用链中执行，Xdebug 若未提前挂载或路径映射错位，就会直接略过。
- 确保
public/index.php是唯一入口，且第一行就设断点——这是验证 Xdebug 连通性的“心跳线” - 不要只在控制器方法里打点，必须手动在
think\Route::dispatch()和think\Pipeline::then()内部关键位置加断点（它们是中间件调度的枢纽） - 检查
php.ini中是否启用xdebug.mode = debug且xdebug.start_with_request = yes；CLI 模式下还需额外传环境变量XDEBUG_CONFIG="idekey=PHPSTORM" - 若用多应用结构（如 TP6+），确认
app/目录已标记为Sources Root，否则 PhpStorm 解析不到自定义中间件类的类型
如何让中间件里的 $this->app 或 app('request') 补全 + 断点可用
框架大量使用容器绑定和魔术属性，PhpStorm 静态分析时无法推导真实类型，导致断点能命中但变量值为空、补全失效。
- 在中间件类开头显式声明属性类型：
/** @var \think\App $app */ - 对容器获取对象统一加类型断言注释：
$request = app('request'); /** @var \think\Request $request */ - 避免直接访问未声明的
$this->request—— ThinkPHP 5.1+ 已不推荐，改用$this->app->make('request')或构造器注入 - 别把
Settings → Editor → Inspections → PHP → Undefined class设为“严重错误”，否则满屏红色干扰调试节奏
HTTP Client 调接口时中间件不触发？检查这四点
用 PhpStorm 内置 HTTP Client 测试路由或中间件行为时，常出现“请求发出去了但断点完全不进中间件”的情况，本质是请求没走框架完整生命周期。
- 文件后缀必须是
.http或.rest，且首行严格为GET http://localhost:8000/api/test（顶格、大写方法、无注释、URL 全路径） - 必须显式携带
XDEBUG_SESSION_START: PHPSTORM请求头，仅靠 URL 参数?XDEBUG_SESSION_START=PHPSTORM不可靠 - 确保项目根目录下有
php.ini对应的 Xdebug 配置生效，且xdebug.client_host指向127.0.0.1（Windows 下不能写localhost） - 如果用 Swoole 或 RoadRunner 等常驻进程模型，Xdebug 会因进程复用而失效——此时必须关掉常驻模式，退回 FPM/CLI 调试
CLI 模式调试中间件脚本为什么连不上
运行 php think middleware:install 类命令时断点不生效，不是 Xdebug 没装，而是 IDE 没告诉它“这次要调试的是 CLI 上下文”。
立即学习“PHP免费学习笔记（深入）”；
- 在
Run → Edit Configurations中新增PHP Script类型配置，而不是用默认的PHP Web Page - Script path 填绝对路径（如
D:\project\think），不能用相对路径或命令别名 - Environment variables 栏手动添加
XDEBUG_CONFIG=idekey=PHPSTORM，Windows 下还要勾选Include system environment variables - CLI 脚本若含
exit()或die()提前终止，Xdebug 日志会显示Connection closed by client—— 把退出逻辑换成return或延后执行
实际调试中间件最易忽略的一点：框架内部大量使用 call_user_func_array() 和 ReflectionMethod::invokeArgs() 执行中间件 handle 方法，Xdebug 在这种动态调用链中默认不自动挂起。必须确保断点落在 handle 方法体第一行，且该方法签名被 PhpStorm 正确识别（依赖前面说的类型注释和 Sources Root 标记）。
