Laravel事务失败时可通过五种方法记录详细上下文：一、闭包异常捕获并手动记录查询日志与堆栈；二、监听TransactionFailed事件获取PDO错误与SQL；三、重写handleBeginTransactionException捕获连接级异常；四、用DB::listen关联事务ID与查询日志；五、扩展Telescope注入事务失败条目。

如果您在 Laravel 应用中执行数据库事务时发生异常，但日志中仅显示通用错误信息而缺乏 SQL 语句、绑定参数、事务堆栈等上下文，则无法快速定位问题根源。以下是记录 Laravel 事务失败时详细错误上下文的多种方法：

一、使用 DB::transaction 的闭包异常捕获并手动记录上下文

该方法通过显式捕获事务闭包抛出的异常，在 catch 块中访问当前查询日志、事务状态及原始异常堆栈，从而构建完整上下文。

1、在配置文件 config/database.php 中确保 'logging' => true（Laravel 9+ 默认启用查询日志）或在运行时调用 DB::enableQueryLog()。

2、在事务代码块外初始化一个空数组用于暂存查询日志：$queryLog = [];

3、在事务闭包执行前调用 DB::getQueryLog() 获取已有日志，并在闭包内再次获取以提取本次事务相关查询：DB::flushQueryLog() 必须在事务开始前调用，否则日志可能混杂其他请求查询。

4、在 catch 块中组合异常消息、$e->getTraceAsString()、DB::getQueryLog() 结果以及 DB::transactionLevel() 值，写入自定义日志通道。

二、监听 IlluminateDatabaseEventsTransactionFailed 事件

Laravel 在 8.x 及以上版本原生触发 TransactionFailed 事件，该事件对象包含 Connection 实例和原始异常，可从中提取底层 PDO 错误码、SQLSTATE 及最近执行的 SQL。

1、运行 php artisan make:listener LogTransactionFailure --event="Illuminate\Database\Events\TransactionFailed"

2、在 listener 的 handle 方法中调用 $event->connection->getPdo()->errorInfo() 获取驱动级错误详情。

3、调用 $event->connection->getRecordedQuery()（需先启用 query log）或遍历 $event->connection->getQueryLog() 提取事务内全部语句。

4、使用 Log::channel('transaction')->error('Transaction failed', [ 'exception' => $event->exception, 'sql' => $sql, 'bindings' => $bindings, 'pdo_error' => $pdoError ])

三、重写 IlluminateDatabaseConnection 的 handleBeginTransactionException 方法

该方法在 beginTransaction 抛出异常时被调用，属于底层事务启动失败的捕获点，适用于连接超时、锁等待超时等前置失败场景。

1、创建 AppDatabaseMySqlConnection 继承 IlluminateDatabaseMySqlConnection（或其他对应驱动类）。

2、重写 handleBeginTransactionException 方法，在调用 parent::handleBeginTransactionException($e) 前插入日志逻辑。

3、从 $this->getConfig() 中提取数据库名与主机，结合 $e->getMessage() 和 $e->getTrace()[0] 中的文件行号，生成带环境标识的上下文日志。

4、在 config/database.php 的 connections.mysql.driver 项中替换为自定义类名：必须同时修改 use 语句并确保自动加载生效。

四、利用 DB::listen 回调过滤事务内查询并关联异常堆栈

DB::listen 可监听每条执行的 SQL，配合静态变量标记事务生命周期，将查询与后续抛出的异常进行时间戳或唯一 ID 关联。

1、在事务开始前设置静态标识：static $currentTransactionId = Str::uuid()->toString();

2、注册 DB::listen 回调，当检测到 DB::transaction 正在执行时，将每条查询连同 $currentTransactionId、$query、$bindings、microtime(true) 写入内存数组。

3、在事务 catch 块中，遍历该内存数组，筛选出 $currentTransactionId 匹配且时间在异常发生前 5 秒内的所有查询记录。

4、将筛选结果与异常对象一起格式化为 JSON，写入 storage/logs/transaction-context-YYYY-MM-DD.log 文件：注意清空内存数组防止内存泄漏。

五、使用 Laravel Telescope 的事务钩子扩展

Telescope 默认不记录事务失败上下文，但可通过其 EntryType 扩展机制注入自定义事务失败条目，包含完整 SQL 流水、异常堆栈和绑定参数快照。

1、创建 AppTelescopeTransactionFailureEntry 类实现 IlluminateTelescopeEntryContract。

2、在 AppProvidersTelescopeServiceProvider 的 register 方法中调用 Telescope::filter() 并监听 TransactionFailed 事件。

3、在事件处理器中构造 TransactionFailureEntry 实例，传入 $event->exception、$event->connection->getQueryLog() 和 DB::pretend() 状态标识。

4、在 Telescope UI 中访问 /telescope/entries 页面，筛选 Entry Type 为 transaction-failure，查看结构化上下文数据：需确保 APP_ENV=local 或 TELESCOPE_ENABLED=true。