问题描述：Laravel 日志中异常链堆栈追踪的缺失
Laravel 框架默认使用 Monolog 作为其日志底层库。在处理异常时，尤其是当应用采用“异常链”（Chained Exceptions）模式，即捕获一个异常后，再抛出一个新的异常并附带上一个异常作为 previous 属性时，Monolog 1.x 版本的 LineFormatter 可能会出现一个问题：它在日志中仅输出最外层（最新抛出）异常的堆栈追踪，而忽略了异常链中所有前置（原始）异常的堆栈追踪信息。
这与 Laravel 控制台输出的体验形成鲜明对比。Laravel 控制台使用的 nunomaduro/collision 包能够智能地合并并展示整个异常链的堆栈追踪，极大地方便了开发者定位问题的根源。然而，在日志文件中，这种缺失的堆栈追踪信息，特别是原始异常的堆栈，使得调试变得异常困难，因为真正的错误根源往往隐藏在链条的深处。
考虑以下一个典型的异常链示例：
getCode(), $e);
}
}
function method2()
{
try {
method3();
} catch (\Exception $e) {
throw new \Exception('调用 method2 失败，因为出现问题', $e->getCode(), $e);
}
}
function method3()
{
// 我们期望在日志中看到此原始异常的堆栈追踪，或者更好的是，所有三个异常的合并堆栈追踪。
throw new \Exception('糟糕，出错了！');
}在此示例中，method3 抛出了最初的异常，随后 method2 和 method1 捕获并重新抛出，形成了异常链。如果日志中只显示 method1 抛出异常的堆栈，那么定位 method3 中的错误将变得非常困难。
根源分析与解决方案
经过深入分析，此问题主要源于 Monolog 1.x 版本中 LineFormatter 的行为限制。在 Monolog 1.x 中，LineFormatter 默认情况下不会递归地处理异常链中的 previous 异常，导致日志中仅包含最外层异常的堆栈追踪信息。
幸运的是，Monolog 2.x 版本已经通过其内部改进（具体可参考 Monolog 的 GitHub Pull Request #1170）彻底解决了 LineFormatter 的这一问题，使其能够正确地输出异常链中所有异常的堆栈追踪。
基于此，我们有两种主要的解决方案：
方案一：升级 Monolog 至 2.x 版本（推荐）
最推荐且最直接的解决方案是：将项目中的 Monolog 依赖升级到 2.x 版本。值得注意的是，Laravel 6.x 版本完全支持 Monolog 2.x，因此升级通常不会引入兼容性问题。Monolog 2.x 的 LineFormatter 已内建了对异常链的完整支持，无需额外配置。
操作步骤：
-
修改 composer.json： 打开项目根目录下的 composer.json 文件，找到 require 部分，将 monolog/monolog 的版本约束修改为允许 2.x 版本，例如：
{ "require": { // ... 其他依赖 "monolog/monolog": "^2.0" // 确保版本兼容 2.x } }如果您当前是 ^1.0，直接改为 ^2.0 即可。
-
更新 Composer 依赖： 在项目根目录执行 Composer 更新命令：
composer update monolog/monolog
此命令会下载并安装 Monolog 的最新 2.x 版本。
-
清除缓存（可选但推荐）： 升级依赖后，为了确保 Laravel 能够正确加载新的类和配置，建议清除框架缓存：
php artisan cache:clear php artisan config:clear
完成上述步骤后，您的 Laravel 应用在记录异常时，Monolog 2.x 的 LineFormatter 将自动输出完整的异常链堆栈追踪信息。
方案二：为 Monolog 1.x 使用替代 Formatter 或自定义 Formatter
如果由于项目存在其他依赖冲突，或有特殊需求导致无法将 Monolog 升级到 2.x 版本，那么可以考虑在 Monolog 1.x 环境下通过配置不同的 Formatter 或自定义 Formatter 来解决此问题。
-
尝试其他内置 Formatter： Monolog 提供了多种内置的 Formatter，例如 JsonFormatter、HtmlFormatter 等。这些 Formatter 在处理异常时，其行为可能与 LineFormatter 有所不同，有些可能默认就能包含更完整的异常信息。您可以尝试在 config/logging.php 中修改特定日志通道的 formatter 配置，例如：
// config/logging.php 'channels' => [ // ... 其他通道配置 'single' => [ 'driver' => 'single', 'path' => storage_path('logs/laravel.log'), 'level' => 'debug', // 尝试更换 Formatter，例如使用 JsonFormatter 'formatter' => Monolog\Formatter\JsonFormatter::class, // 如果使用 JsonFormatter，通常不需要 'formatter_with' 中的 'format' 键， // 但可以配置其他 JsonFormatter 的选项，如 batchMode 等 'formatter_with' => [ 'batchMode' => Monolog\Formatter\JsonFormatter::BATCH_MODE_NEWLINES, 'includeStacktraces' => true, // 确保包含堆栈追踪 ], ], // ... ],使用 JsonFormatter 或 HtmlFormatter 等通常会以更结构化的方式输出日志，其中可能包含完整的异常对象，包括其 previous 属性。
-
自定义 Monolog Formatter： 如果内置 Formatter 仍不满足需求，或者您希望保留 LineFormatter 的输出风格，可以自定义一个继承自 Monolog\Formatter\LineFormatter 的类，并重写其 format 方法，以递归地处理异常链。这个自定义 Formatter 的核心逻辑将类似于 Monolog 2.x 中 LineFormatter 的改进，即在格式化异常时，遍历其 previous 属性，将所有前置异常的堆栈追踪信息也包含进来。
步骤：
a. 创建自定义 Formatter 类： 在 app/Logging/Formatters 目录下（如果不存在请创建）创建 CustomLineFormatter.php 文件：
```php // app/Logging/Formatters/CustomLineFormatter.php namespace App\Logging\Formatters; use Monolog\Formatter\LineFormatter; use Throwable; /** * 扩展 Monolog 的 LineFormatter，以包含异常链中所有前置异常的堆栈追踪。 * 注意：实际实现会比此示例复杂，建议参考 Monolog 2.x 的 LineFormatter 源码。 */ class CustomLineFormatter extends LineFormatter { /** * 构造函数，可以设置格式等参数 * @param string|null $format * @param string|null $dateFormat * @param bool $allowInlineLineBreaks * @param bool $ignoreEmptyContextAndExtra */ public function __construct( ?string $format = null, ?string $dateFormat = null, bool $allowInlineLineBreaks = false, bool $ignoreEmptyContextAndExtra = false ) { // 默认格式，可以根据需要调整，确保能显示 extra 字段 $defaultFormat = "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"; parent::__construct( $format ?? $defaultFormat, $dateFormat, $allowInlineLineBreaks, $ignoreEmptyContextAndExtra ); } /** * 格式化一条日志记录。 * 核心逻辑是提取并格式化异常链中的所有堆栈追踪。 */ public function format(array $record): string { // 检查是否存在异常，并且是 Throwable 类型 if (isset($record['context']['exception']) && $record['context']['exception'] instanceof Throwable) { $exception = $record['context']['exception']; $fullExceptionTrace = ''; $i = 0; do { $fullExceptionTrace .= sprintf( "--- Exception #%d (%s) ---\nMessage: %s\nFile: %s:%d\nTrace:\n%s\n", ++$i, get_class($exception), $exception->getMessage(), $exception->getFile(), $exception->getLine(), $exception->getTraceAsString() ); // 获取前一个异常 $exception = $exception->getPrevious(); } while ($exception); // 将完整的异常链堆栈追踪添加到 extra 字段，以便父类格式化时包含 $record['extra']['full_exception_trace'] = $fullExceptionTrace; } // 调用父类的 format 方法来完成最终的格式化 return parent::format($record); } } ``` **注意：** 上述 `CustomLineFormatter` 的 `format` 方法是一个简化示例，旨在演示如何遍历异常链。实际的生产级实现可能需要更精细的格式控制和错误处理，以确保与 Monolog 2.x `LineFormatter` 的行为一致。您可以参考 Monolog 2.x `LineFormatter` 的源代码来获取更完善的实现细节。b. 配置 Laravel 日志使用自定义 Formatter： 打开 config/logging.php 文件，找到您需要修改的日志通道（例如 single），将 formatter 配置指向您的自定义类：
```php // config/logging.php 'channels' => [ // ... 'single' => [ 'driver' => 'single', 'path' => storage_path('logs/laravel.log'), 'level' => 'debug', 'formatter' => App\Logging\Formatters\CustomLineFormatter::class, 'formatter_with' => [ // 自定义格式，确保包含 %extra% 或 %extra.full_exception_trace% 'format' => "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n", 'dateFormat' => "Y-m-d H:i:s", 'allowInlineLineBreaks' => true, 'ignoreEmptyContextAndExtra' => true, ], ], // ... ], ``` 请注意 `formatter_with` 中的 `format` 字符串，它决定了日志行的最终输出格式。确保其中包含 `%extra%` 或直接引用您在 `CustomLineFormatter` 中添加的 `full_exception_trace` 键，以便这些信息能被打印出来。
注意事项与总结
- 优先升级 Monolog： 在大多数情况下，将 Monolog 升级到 2.x 是最推荐且最稳健的解决方案，因为它直接从源头解决了问题，并且与 Laravel 6.x 兼容，维护成本最低。
- 测试是关键： 无论采用哪种方案，在生产环境部署之前，务必在开发或测试环境中进行充分的测试，确保日志输出符合预期，并且没有引入新的问题。
- 日志的重要性： 完整的异常堆栈追踪对于快速定位和解决问题至关重要，尤其是在复杂的应用中，异常链能够清晰地展现
