ThinkPHP 数据库配置文件 debug 模式开关【调试】

关于 ThinkPHP 的数据库调试，有两个问题经常让人一头雾水：一是“到底该在哪里开这个调试模式”，二是“明明开了，SQL 怎么就是看不到”。今天就把这两件事一次性讲清楚。

首先明确一点，ThinkPHP 的数据库调试不由数据库配置文件独立控制——config/database.php 或者 .env 里并没有一个叫 debug 的开关。真正驱动这一切的是全局常量 APP_DEBUG。这个开关一旦打开，框架会自动开启数据库层的 SQL 日志记录、执行时间统计以及参数绑定详情等调试能力。换句话说，它是一把总钥匙。

当然，你可以在数据库配置中设置 'log' => ['enable' => true] 来增强调试，但这属于锦上添花，不是必要条件——因为 APP_DEBUG 已经默认让日志生效了。反过来，如果 APP_DEBUG 是 false，那无论数据库配置怎么折腾，SQL 日志和调试信息都不会出现在页面或者 trace 面板上。

那么，要让 SQL 调试信息真正可见，需要满足哪几个条件？

第一，入口文件顶部必须定义 define('APP_DEBUG', true)，而且这条定义必须在任何 require 语句之前执行。第二，trace 工具栏需要启用，通过 define('APP_TRACE', true) 或者在 .env 中写入 APP_TRACE=true 来实现。第三，数据库配置中不能禁用日志，比如避免出现 'log' => ['enable' => false] 这样的写法。三个条件缺一不可。

敏感信息防护提醒

数据库调试开启后，原始 SQL 和绑定参数（包括密码、token 等敏感数据）会直接暴露在 trace 面板或 runtime/log/ 目录下。这里必须强调一个底线：生产环境绝对不能开启 APP_DEBUG。如果确实需要保留日志但隐藏敏感内容，可以在数据库配置中用 'log' => ['record' => ['sql', 'time']] 来排除 params。另外，记得检查一下 config/log.php 中的 level 配置是否包含了 'sql'，否则 trace 面板的 SQL 标签页很可能是一片空白。

验证是否生效的快速方法

最后，给一个简单的验证流程。在控制器中执行一条查询，比如 Db::table('user')->find();，然后分三步确认：页面的右下角有没有出现 Trace 小图标？点击后能否看到 SQL 标签页？runtime/log/ 目录下是否生成了类似 sql_20260708.log 的文件？如果还有疑虑，可以直接执行 var_dump(thinkApp::debug())，返回 true 就说明调试模式已经正常生效。