日誌 - 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 錯誤日誌
`monolog`	直接指定 Monolog handler
`custom`	由 factory 類別完全自訂通道

日誌等級

Laravel 支援 RFC 5424 定義的 8 個日誌等級。以嚴重度由高至低排列。

等級	使用範例
`emergency`	整個系統無法使用，需立即處理
`alert`	需人立即介入的狀態（例如 DB 連線中斷）
`critical`	主要功能停擺的重大故障
`error`	執行期錯誤，需處理但未必立即
`warning`	潛在問題，如使用不建議 API 或非預期資料
`notice`	正常但值得注意
`info`	使用者登入、訂單確立等一般操作日誌
`debug`	開發期詳細除錯資訊

通道的 level 設定代表最低日誌等級。例如 level 為 error 時，僅會寫入 error 及以上等級（critical、alert、emergency）。

基本用法

Log Facade

透過 Illuminate\Support\Facades\Log Facade 撰寫各等級的訊息。

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 Facade 也能使用。

log('來自 helper 的日誌。');

// 也可以指定等級與 context
log('已建立使用者。', 'info', ['user_id' => $user->id]);

附加脈絡（context）

將訊息與陣列的脈絡一併傳入，可統整記錄相關資訊。

Log::info('登入失敗。', [
    'user_id' => $user->id,
    'ip'      => $request->ip(),
    'reason'  => '密碼不符',
]);

withContext() — 對整個通道加上共通脈絡

若想對特定通道之後所有日誌都附上共通資訊，可以用 withContext()。適合用來附上像 request 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 匯入。');

實用範例

於中介軟體加上 request ID

為所有日誌加上共通的 request 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

# 顯示 stack trace
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`	使用不建議 API 或出現非預期資料等需注意情況
`notice`	正常但值得記錄的重要操作
`info`	使用者操作或商業事件的紀錄
`debug`	開發期詳細除錯資訊（正式環境不需要）

通道選擇指南

開發環境：使用 single 或 daily 寫入檔案
正式環境：以 stack 結合 daily（檔案保存）與 slack（錯誤通知）
特定處理的日誌：以 Log::build() 建立隨用即建通道寫入獨立檔案
即時監控：以 php artisan pail 從終端機查看

正式環境注意事項

debug 日誌可能包含機密資訊。正式環境建議 LOG_LEVEL=error 以上。
請定期輪換日誌檔避免磁碟爆滿（daily 通道的 days 設定）。
傳送到 Slack 等外部服務時請注意速率限制。應設定等級只通知重大錯誤。

​日誌是什麼

​設定

​可用的通道驅動

​日誌等級

​基本用法

​Log Facade

​log() 輔助函式

​附加脈絡（context）

​withContext() — 對整個通道加上共通脈絡

​shareContext() — 對所有通道加上共通脈絡

​通道設定

​stack 通道 — 同時寫入多個通道

​daily 通道 — 日誌循環

​錯誤通知到 Slack

​寫入特定通道

​隨用即建的通道

​實用範例

​於中介軟體加上 request ID

​記錄不建議使用的警告

​Laravel Pail — 即時日誌監控

​安裝

​基本用法

​日誌過濾

​總結

日誌是什麼

設定

可用的通道驅動

日誌等級

基本用法

Log Facade

log() 輔助函式

附加脈絡（context）

withContext() — 對整個通道加上共通脈絡

shareContext() — 對所有通道加上共通脈絡

通道設定

stack 通道 — 同時寫入多個通道

daily 通道 — 日誌循環

錯誤通知到 Slack

寫入特定通道

隨用即建的通道

實用範例

於中介軟體加上 request ID

記錄不建議使用的警告

Laravel Pail — 即時日誌監控

安裝

基本用法

日誌過濾

總結