如何优雅地集成ThinkPHP开发环境中的SQL配置DebugBar日志查看功能？

本文共计848个文字，预计阅读时间需要4分钟。

默认开启 + `app_debug` 并不自动打印 SQL，必须显式启用数据库日志记录。核心是配置项 + `database.logger.sql` + 和 + `log.level` + 的组合生效。

• database.logger.sql 设为 true（TP6.1+）或 database.log_sql（旧版），否则 SQL 根本不进日志管道
• log.level 至少设为 debug，否则 sql 级别日志被过滤掉
• 如果用的是 Swoole 或 RoadRunner，日志可能写入文件但不实时刷屏，得查 runtime/log/ 下的日期文件

DebugBar 在 ThinkPHP 6 中集成失败的典型原因

DebugBar 不是开箱即用的扩展，TP6 默认不加载中间件、不注入收集器，手动集成时最容易卡在生命周期钩子缺失。

• 必须在 app/middleware.php 中注册 DebugbarMiddleware，且顺序要靠前（比如放在 AllowCrossDomain 之前）
• thinkphp-debugbar 包的 DebugbarCollector 需要手动绑定到容器，否则 SQL、路由等数据不会被捕获
• 前端资源（CSS/JS）路径不对：DebugBar 默认从 /debugbar/ 加载，需确认 Nginx/Apache 是否放行该路由，或改用 debugbar.open_handler 配置为 file 方式

SQL 显示乱码、参数未替换、带问号占位符？

这是 PDO 预处理语句的原始日志形态，不是 Bug，但影响排查效率。真正执行的 SQL 要靠 DebugBar 的「Query」面板展开看「full_sql」字段，或者改用日志格式化。

• 开启 database.replace_placeholders（TP6.2+）可自动将 ? 替换为实际值，但仅限简单类型，NULL 和数组仍显示为 NULL 或 Array
• 如果用了 Db::raw() 或闭包查询，参数不会被解析，DebugBar 只能显示原始字符串，此时得配合 trace 手动打点
• 注意 database.fetch_sql 是调试开关，开启后会中断执行并返回 SQL 字符串，别在线上环境开着

为什么 DebugBar 显示 SQL 条数对不上、漏了事务里的语句？

DebugBar 的 SQL 收集依赖于数据库连接实例的生命周期，而 TP6 的事务操作（如 Db::transaction()）可能复用连接但绕过常规执行钩子。

立即学习“PHP免费学习笔记（深入）”；

• 确保事务内所有操作都走 Db:: 或模型方法，直接调 $pdo->exec() 不会被捕获
• 如果用了多库连接（Db::connect('other')），要单独为该连接注册 DebugbarCollector，否则只监控默认库
• DebugBar 默认每页最多记录 100 条 SQL，超量会被截断，可通过 debugbar.options.max_messages 调整

最常被忽略的是：DebugBar 的 SQL 数据来自「执行完成」事件，但 ThinkPHP 的 after_transaction 钩子在事务提交后才触发，所以回滚场景下部分语句可能根本没进收集器——真要盯事务细节，得结合 trace + Log::record() 手动埋点。