ThinkPHP调试失败的核心原因是调试开关未真正开启、错误被拦截或调试方式错误；需确保APP_DEBUG在入口文件顶部定义、开启错误显示与报告、清空runtime目录，并配合Trace、SQL日志及halt/Log等正确调试手段。
ThinkPHP环境搭好后调试不起来，通常不是框架有问题，而是调试开关没真正打开、底层错误被拦截、或调试方式用错了。核心就三点：让错误露出来、让日志记下来、让变量看得见。
一、先确认调试模式是否真实生效
APP_DEBUG必须在public/index.php最顶部、任何require之前定义，晚一秒都无效。别改config/app.php或只写.env——这些只是后备，框架加载时早就不认了。
- 在public/index.php第一行插入：define('APP_DEBUG', true);
- 紧跟着加两行：ini_set('display_errors', '1'); error_reporting(E_ALL);
- 删掉整个runtime/目录（含~runtime.php），清空缓存
- 刷新页面，看到带堆栈的红色错误页才算成功；如果还是“页面错误！请稍后再试～”，说明没生效
二、接口返回500却看不到详情？重点查三处
前后端分离项目里，接口报500但响应是空的或HTML错误页，大概率是错误输出被关了、格式没统一、或路径有中文。
- 检查PHP是否真开了错误显示：
php -i | findstr "display_errors error_reporting"，确保display_errors=On且error_reporting≥32767 - 接口异常要强制返回JSON：在app/exception/Handler.php的render()方法中，用
response()->json(['code'=>500, 'msg'=>$e->getMessage()], 500)，别用return json() - 项目路径含中文（如C:\用户\xxx\project）会导致JSON编码失败并静默500，换成纯英文路径测试
三、想看SQL和请求流程？Trace工具栏+日志双开
APP_DEBUG开了，不代表Trace面板和SQL日志自动出来，它们各自有开关，且只对HTTP请求生效。
立即学习“PHP免费学习笔记（深入）”；
- 开启Trace：在.env中加
APP_TRACE=true（等号两边不能有空格），或在入口文件define('APP_DEBUG', true)后加define('APP_TRACE', true) - 开启SQL日志：在database.php配置中设
'log' => ['enable' => true]，日志会写入runtime/log/，文件名带日期 - 注意：Trace只在HTML响应时显示右下角小图标，AJAX接口不会渲染它；查SQL可用
Db::getLastSql()或监听sql_explain事件
四、dump()不好使？换更稳的调试方式
dump()在控制器里能用，但在中间件、队列任务、Swoole子进程里常失效，还容易触发headers already sent错误。
- 页面中断调试优先用
halt($data)，它不依赖响应头，直接输出并终止 - 后台逻辑调试用
Log::info('描述', ['data' => $data])，日志稳定写入runtime/log/ - 命令行调试插件（如queue:work）时，别靠浏览器触发，要用CLI模式启动，并在PhpStorm里配好vendor路径映射，否则断点根本进不去
