Trace 不显示主因是 APP_DEBUG 未正确定义或 APP_TRACE 环境变量未生效，需在入口文件顶部定义 APP_DEBUG=true、确保 .env 中 APP_DEBUG=true 和 APP_TRACE=true（无空格、UTF-8无BOM）、安装 think-trace 扩展、清空 runtime 目录并检查日志 level 包含 'sql'。
app_trace 配置开启后看不到 Trace，大概率不是 app_trace 本身没生效，而是整个调试链路卡在了更前置的环节——APP_DEBUG 没真正启动，或 APP_TRACE 开关未被识别。
入口文件没定义 APP_DEBUG 或位置错了
ThinkPHP 在框架加载极早期就检查 APP_DEBUG 常量。如果它没定义，或者定义在 require 框架启动文件（如 thinkphp/start.php）之后，整个调试系统（包括 Trace 渲染、SQL 日志、异常堆栈）都会静默失效。
- 常见错误现象：
.env里写了APP_DEBUG=true，但页面还是“页面错误，请稍后再试~”；config/app.php改了'app_debug' => true，右下角图标仍不出现 - 实操建议：打开
public/index.php，在文件最顶部、任何require或include之前插入两行：define('APP_DEBUG', true);<br>ini_set('display_errors', '1'); - 删掉整个
runtime/目录（含子目录），否则旧缓存会干扰新配置
APP_TRACE 没启用或环境变量被跳过
app_trace => true 是旧版 ThinkPHP5 的配置项，TP6/TP8 已不再直接读取它。新版依赖的是 APP_TRACE 环境常量，且必须和 APP_DEBUG 同时为 true 才会注入 Trace HTML。
- 常见错误现象：图标不显示、点击无反应、面板空白；即使装了
think-trace扩展也没用 - 实操建议：
– 确保项目根目录有.env文件，内容严格为（等号两侧**不能有空格**，编码必须是 UTF-8 无 BOM）：APP_DEBUG=true<br>APP_TRACE=true
– TP6+ 必须运行composer require topthink/think-trace安装扩展包
– 如果入口文件顶部已定义APP_DEBUG，TP8 会跳过.env加载，导致APP_TRACE失效，此时应统一用.env管理，入口文件里不要重复定义
Trace 只对 HTML 响应生效，JSON 接口不会渲染
Trace 面板是通过向响应体末尾注入 HTML + JS 实现的，所以它只会在返回 text/html 的请求中出现。API 接口返回 application/json 时，无论怎么配都不会显示右下角图标——这不是 bug，是设计行为。
立即学习“PHP免费学习笔记（深入）”；
- 验证方式：访问一个带模板输出的路由（如
/index或/admin），而不是/api/user - 如果必须调试 JSON 接口逻辑，改用：
– 控制器中调用trace('xxx')写入日志
– 查看runtime/log/下对应日期的 log 文件
– 或临时把接口改成return view(...)辅助定位 - 注意：有些中间件（如 CORS、JWT 验证）可能提前终止响应或修改 header，也会导致 Trace 注入失败
SQL 标签页为空？别只盯 app_trace
Trace 面板里的 “SQL” 标签页内容来自日志系统，不是实时抓取。即使 APP_TRACE=true，如果日志级别没包含 sql，标签页只会显示数量，不展示语句。
- 检查
config/log.php中的level配置，确保包含'sql'：return [<br> 'level' => ['error', 'sql', 'notice'],<br>];
- 如果用了自定义数据库连接（如读写分离），确认所有连接都启用了
trace_sql（默认开启，但手动关闭过需复查） - 更可靠抓 SQL 的方式是在出问题的方法开头加监听：
Db::listen(function ($sql, $time, $explain) {<br> dump($sql);<br>});这拿到的是真实执行语句，含表前缀、软删除条件、时间类型转换等
最常被忽略的一点：TP8 的配置缓存固化在 runtime/container/ 和 runtime/cache/ 里，改了 .env 不清缓存 = 白改；.env 有 BOM 或权限不可写，框架会静默跳过加载——这两处一错，APP_TRACE 就彻底失效。
