日志记录 - Knowledge of Laravel

什么是日志

Laravel 的日志系统以**通道（Channel）**这一概念为核心进行设计。通道是定义日志写入目标和方式的配置单位，可以组合文件、Slack、syslog 等多种输出目标。内部使用 Monolog 库，可以利用其丰富的 handler 与 formatter。

默认使用的是 stack 通道。stack 是把多个通道集中管理的父通道。

配置

日志的配置集中在 config/logging.php。可通过环境变量 LOG_CHANNEL 切换默认通道。

// config/logging.php
'default' => env('LOG_CHANNEL', 'stack'),

可用的通道驱动

驱动	说明
`single`	将所有日志写入一个文件
`daily`	按日期分文件写入（带轮转）
`slack`	通过 Slack 的 Incoming Webhook 发送消息
`stack`	统一管理多个通道的父通道
`syslog`	写入系统 syslog
`errorlog`	写入 PHP 的 error log
`monolog`	直接指定 Monolog 的 handler
`custom`	使用工厂类完全自定义通道

日志级别

Laravel 支持 RFC 5424 定义的 8 个日志级别。按严重程度从高到低排列。

级别	用途示例
`emergency`	整个系统不可用，需立即响应
`alert`	需要人立即介入的状态（如数据库连接中断）
`critical`	应用主要功能停止的严重故障
`error`	运行时错误。需要处理但不一定立即
`warning`	潜在问题。如使用了弃用 API 或出现非预期数据
`notice`	正常运行但值得关注的信息
`info`	用户登录、订单确认等常规操作日志
`debug`	开发中的详细调试信息

通道的 level 配置意味着最低日志级别。例如 level 为 error 时，只写入 error 及以上（critical、alert、emergency）。

基本用法

Log 门面

使用 Illuminate\Support\Facades\Log 门面写入各级别消息。

use Illuminate\Support\Facades\Log;

Log::emergency('系统已停止。');
Log::alert('数据库连接已中断。');
Log::critical('支付服务无响应。');
Log::error('用户数据更新失败。');
Log::warning('调用了弃用的方法。');
Log::notice('配置文件已被重新加载。');
Log::info('用户已登录。');
Log::debug('查询执行时间: 42ms');

在控制器中的使用示例：

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;

class UserController extends Controller
{
    public function show(string $id): View
    {
        Log::info('显示用户资料。', ['user_id' => $id]);

        return view('user.profile', [
            'user' => User::findOrFail($id),
        ]);
    }
}

log() 辅助函数

使用 log() 辅助函数可无需 import Log 门面即可写日志。

log('来自辅助函数的日志。');

// 也可以指定级别和上下文
log('已创建用户。', 'info', ['user_id' => $user->id]);

添加上下文信息

在消息之外传入上下文（数组），可将相关信息一并记录。

Log::info('登录失败。', [
    'user_id' => $user->id,
    'ip'      => $request->ip(),
    'reason'  => '密码不匹配',
]);

withContext() — 为整个通道附加公共上下文

若希望为某个特定通道之后所有日志条目附加公共信息，可使用 withContext()。适合像请求 ID 这样希望在所有日志中包含的信息。

Log::withContext(['request-id' => (string) Str::uuid()]);

// 之后的所有日志都会自动包含 request-id
Log::info('开始处理。');
Log::error('发生了错误。');

shareContext() — 为所有通道附加公共上下文

withContext() 只对目标通道生效，而 shareContext() 会为所有通道附加公共上下文。

Log::shareContext(['app-version' => config('app.version')]);

通道配置

stack 通道 — 同时写入多个通道

使用 stack 通道，一次日志调用即可写入多个通道。

// config/logging.php
'channels' => [
    'stack' => [
        'driver'   => 'stack',
        'channels' => ['daily', 'slack'],
    ],

    'daily' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/laravel.log'),
        'level'  => env('LOG_LEVEL', 'debug'),
        'days'   => 14,
    ],

    'slack' => [
        'driver'   => 'slack',
        'url'      => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji'    => env('LOG_SLACK_EMOJI', ':boom:'),
        'level'    => 'critical',
    ],
],

在该配置下，debug 及以上的所有日志会写入 daily（文件），而仅 critical 及以上会同时发送到 slack。

在生产环境建议将 slack 通道的级别设置为 error 或 critical。若把琐碎日志都推送到 Slack，通知会过多，重要告警可能被淹没。

daily 通道 — 日志轮转

daily 通道会按日期分文件，并自动删除旧文件。

'daily' => [
    'driver' => 'daily',
    'path'   => storage_path('logs/laravel.log'),
    'level'  => env('LOG_LEVEL', 'debug'),
    'days'   => env('LOG_DAILY_DAYS', 14), // 保留 14 天
],

减小 days 会更快删除旧日志。为了应对生产环境的故障排查，请保留足够的保留期。

向 Slack 发送错误通知

获取 Slack 的 Incoming Webhook URL 并配置到 .env 中。

LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz

// config/logging.php
'slack' => [
    'driver'   => 'slack',
    'url'      => env('LOG_SLACK_WEBHOOK_URL'),
    'username' => 'Laravel Error Bot',
    'emoji'    => ':fire:',
    'level'    => 'error',
],

将 slack 加入 stack 通道，并设置 LOG_CHANNEL=stack，即可在错误发生时自动通知。

向指定通道写入日志

通过 Log::channel() 可以明确指定目标通道。

// 仅写入 slack 通道
Log::channel('slack')->error('支付服务无响应。');

// 同时写入多个通道
Log::stack(['daily', 'slack'])->critical('数据库连接失败。');

按需通道

使用 Log::build() 可以在不定义配置的前提下临时创建自定义通道。适合测试或写入到临时输出目标的场景。

use Illuminate\Support\Facades\Log;

$channel = Log::build([
    'driver' => 'single',
    'path'   => storage_path('logs/import-' . now()->format('Ymd') . '.log'),
]);

Log::stack([$channel])->info('开始 CSV 导入。');

实践场景

在中间件中附加请求 ID

若为所有日志附加共同的请求 ID，可方便地从日志中追踪特定请求的处理链路。

创建中间件

php artisan make:middleware AssignRequestId

实现 handle() 方法

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AssignRequestId
{
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

        Log::withContext(['request-id' => $requestId]);

        $response = $next($request);

        $response->headers->set('X-Request-Id', $requestId);

        return $response;
    }
}

注册中间件

在 bootstrap/app.php 中注册为全局中间件。

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\AssignRequestId::class);
})

完成上述配置后，所有日志都会自动附加 request-id。

[2026-03-01 12:00:00] local.INFO: 用户已登录。 {"request-id":"550e8400-...","user_id":1}
[2026-03-01 12:00:00] local.INFO: 显示仪表板。 {"request-id":"550e8400-..."}

记录弃用警告

可将使用 PHP 或 Laravel 的弃用功能时的警告写入日志。

// config/logging.php
'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace'   => env('LOG_DEPRECATIONS_TRACE', false),
],

在 .env 中指定通道。

LOG_DEPRECATIONS_CHANNEL=daily

Laravel Pail — 实时日志监控

Laravel Pail 是可在终端实时查看应用日志的开发工具。它与标准 tail 命令不同，设计上兼容包括 Laravel Nightwatch、Sentry、Flare 在内的任何日志驱动。

执行 Pail 需要 PHP 的 PCNTL 扩展。

安装

composer require --dev laravel/pail

基本用法

# 观察日志流
php artisan pail

# 详细显示（不省略）
php artisan pail -v

# 同时显示堆栈跟踪
php artisan pail -vv

日志过滤

# 按关键字过滤
php artisan pail --filter="QueryException"

# 仅按消息过滤
php artisan pail --message="登录"

# 按日志级别过滤
php artisan pail --level=error

# 仅显示特定用户的日志
php artisan pail --user=1

小结

日志级别的选择

级别	使用时机
`emergency`	会导致整个系统停止的致命故障
`alert`	需要人立即介入的状态
`critical`	主要功能不可用的严重故障
`error`	非预期的运行时错误，需要处理
`warning`	弃用使用、非预期数据等需要留意的状态
`notice`	正常但需要记录的重要操作
`info`	用户操作或业务事件的记录
`debug`	开发中的详细调试信息（生产不需要）

通道选择指南

开发环境：使用 single 或 daily 写入文件
生产环境：使用 stack 组合 daily（文件保存）与 slack（错误通知）
特定处理的日志：通过 Log::build() 创建按需通道，写入独立文件
实时监控：通过 php artisan pail 在终端查看

生产环境的注意事项

debug 日志可能包含机密信息。生产环境建议 LOG_LEVEL=error 及以上。
请定期轮转日志文件，避免占满磁盘（daily 通道的 days 配置）。
向 Slack 等外部服务发送通知请注意速率限制。请设置为仅通知严重错误。

​什么是日志

​配置

​可用的通道驱动

​日志级别

​基本用法

​Log 门面

​log() 辅助函数

​添加上下文信息

​withContext() — 为整个通道附加公共上下文

​shareContext() — 为所有通道附加公共上下文

​通道配置

​stack 通道 — 同时写入多个通道

​daily 通道 — 日志轮转

​向 Slack 发送错误通知

​向指定通道写入日志

​按需通道

​实践场景

​在中间件中附加请求 ID

​记录弃用警告

​Laravel Pail — 实时日志监控

​安装

​基本用法

​日志过滤

​小结

什么是日志

配置

可用的通道驱动

日志级别

基本用法

Log 门面

log() 辅助函数

添加上下文信息

withContext() — 为整个通道附加公共上下文

shareContext() — 为所有通道附加公共上下文

通道配置

stack 通道 — 同时写入多个通道

daily 通道 — 日志轮转

向 Slack 发送错误通知

向指定通道写入日志

按需通道

实践场景

在中间件中附加请求 ID

记录弃用警告

Laravel Pail — 实时日志监控

安装

基本用法

日志过滤

小结