DB::listen 仅监听查询构造器和 Eloquent 的 SQL，不捕获原生 PDO、事务细节、迁移及 Schema 语句；需在应用启动早期注册，注意重复注册、队列/命令中手动调用、参数绑定还原、慢/错/高频查询分级处理及生产环境日志优化。
DB::listen 可以监听到所有通过 Laravel 查询构造器和 Eloquent 发出的 SQL，但默认不捕获原生 DB::select() 以外的 PDO 原生调用、事务内部的 prepare/bind 执行细节，也不包含迁移、Schema 构建语句。
监听函数必须在请求生命周期早期注册
监听器需在应用启动阶段绑定，否则可能漏掉初始化过程中的查询（如服务提供者里触发的 Eloquent 查询）。常见注册位置是 AppServiceProvider::boot() 或中间件中，但更稳妥的是在 bootstrap/app.php 底部或 EventServiceProvider 的 boot() 中调用：
DB::listen(function ($query) {
\Log::debug('SQL:', [
'sql' => $query->sql,
'bindings' => $query->bindings,
'time' => $query->time,
'connection' => $query->connectionName,
]);
});
- 监听器是全局单例，重复注册会导致多次触发
- 若使用队列或 Horizon，需在每个 worker 进程中单独注册（例如在
QueueServiceProvider） - 在 Tinker 或 Artisan 命令中监听，需手动调用一次
DB::listen(...)，它不会自动继承 Web 请求的监听配置
捕获参数绑定后的完整 SQL（避免 ? 占位符）
$query->sql 是带 ? 占位符的原始语句，$query->bindings 是参数数组。要看到真实执行语句，需手动替换。注意：不能直接 str_replace，因为字符串值里也可能含 ?；推荐用 Laravel 内置的 Illuminate\Database\Grammar::substituteBindingsIntoRawSql()，但该方法非公开，稳妥做法是复用 Query Builder 的逻辑：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
$sql = $query->sql;
foreach ($query->bindings as $binding) {
$sql = preg_replace('/\?/', is_string($binding) ? "'" . addslashes($binding) . "'" : $binding, $sql, 1);
}
- 数字/布尔/NULL 类型的 binding 不加引号，字符串才需转义并包裹单引号
- 时间类型（如
Carbon）通常已转为字符串，按字符串处理即可 - 大文本或二进制数据（如 JSON、BLOB）直接拼入可能导致日志爆炸，建议截断或跳过记录
区分慢查询、错误查询与高频查询
仅记录所有 SQL 很快会让日志失控。应结合 $query->time（毫秒）、$query->connectionName 和上下文做分级处理：
- 慢查询：记录
$query->time > 500的语句，并附上当前路由、用户 ID（如有） - 错误查询：监听
illuminate.query事件无法捕获异常，需配合DB::transaction()的回调或全局异常处理器中检查PDOException的 SQL 状态码 - 高频查询：用静态数组缓存
md5($query->sql)计数，每 10 秒输出 top 5 重复语句，避免 N+1 场景被淹没
注意：在高并发下频繁写日志会拖慢响应，生产环境建议用异步通道（如 Log::channel('stack') 配合 Slack/Sentry）或采样（例如只记录 1% 的查询）。
真正容易被忽略的是：DB::listen 不监听 Schema 构建操作（如 Schema::create()）、不捕获连接复用时的 ping 查询、也不会反映连接池行为（如 PDO::ATTR_PERSISTENT 开启后的真实连接复用情况）。如果需要全链路 SQL 可视化，得配合数据库代理层（如 ProxySQL）或启用 MySQL 的 general_log（仅限调试环境）。
