萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 捕獲致命錯誤與超時事件:register_shutdown_function 實戰指南

set_error_handler() 無法捕獲 E_ERROR、E_PARSE、E_CORE_ERROR 等致命錯誤,也無法捕獲 max_execution_time 超時終止。唯一可靠方案是 register_shutdown_function():腳本結束前(正常返回、die/exit、致命錯誤、超時)均會執行,配合 error_get_last() 可獲取最後一個錯誤資訊。

核心機制

<?php
// 設定極短執行時間觸發超時(演示用)
ini_set('max_execution_time', 1);

function shutdown() {
    $error = error_get_last();
    if ($error) {
        // 致命錯誤、超時都會在這裡被捕獲
        $msg = "[SHUTDOWN] " . date('Y-m-d H:i:s') . " 
Type: {$error['type']} 
Message: {$error['message']} 
File: {$error['file']} 
Line: {$error['line']}";
        
        error_log($msg);           // 寫入錯誤日誌
        // 可選:發送告警郵件、Slack、釘釘
        // 可選:輸出友善錯誤頁面(僅 CLI/非 headers_sent 時)
    } else {
        // 正常結束
        error_log("[SHUTDOWN] Normal exit at " . date('Y-m-d H:i:s'));
    }
}

register_shutdown_function('shutdown');

// 觸發超時
while (true) { 
    // 空循環消耗 CPU 時間
    // 注意:sleep() 不計入 max_execution_time
}
?>

關鍵差異對照

錯誤類型set_error_handlerregister_shutdown_function
E_WARNING / E_NOTICE / E_DEPRECATED✓ 捕獲✓ 可獲取(error_get_last)
E_ERROR / E_PARSE / E_CORE_ERROR✗ 無法捕獲✓ 可獲取
max_execution_time 超時✗ 無法捕獲✓ 可獲取(type=1 E_ERROR)
exit()/die()✗ 不觸發✓ 執行(error_get_last 為 null)
Exception 未捕獲✗ 不觸發✓ 可獲取(PHP 7+ 會轉為 Error)

進階:區分正常結束與異常結束

function shutdown() {
    $error = error_get_last();
    $isFatal = $error && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR]);
    $isTimeout = $error && $error['type'] === E_ERROR && strpos($error['message'], 'Maximum execution time') !== false;
    
    if ($isFatal) {
        // 記錄致命錯誤
        logError('FATAL', $error);
        // 發送即時告警
        sendAlert("PHP Fatal Error: {$error['message']} in {$error['file']}:{$error['line']}");
    } elseif ($isTimeout) {
        logError('TIMEOUT', $error);
        sendAlert("PHP Timeout: {$error['file']}:{$error['line']}");
    }
    
    // 可選:輸出用戶友善頁面(僅當未輸出 Header 時)
    if (!headers_sent() && ($isFatal || $isTimeout)) {
        header('Content-Type: text/html; charset=utf-8');
        http_response_code(500);
        echo '<h1>系統暫時無法服務,請稍後再試</h1>';
    }
}

注意事項與限制

  1. 無法恢復執行:shutdown 只能記錄/通知/清理,不能繼續中斷的邏輯
  2. 記憶體限制:memory_limit 耗盡導致的致命錯誤,shutdown 可能無法執行(無記憶體分配空間)
  3. sleep() 不計入執行時間:max_execution_time 僅計算 CPU 時間
  4. 多次註冊:register_shutdown_function 可多次呼叫,按註冊順序逆序執行(後註冊先執行)
  5. 物件解構順序:shutdown 執行時物件尚未解構,可安全呼叫物件方法

生產環境整合範例(Monolog + Slack)

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\SlackWebhookHandler;

$log = new Logger('shutdown');
$log->pushHandler(new StreamHandler('/var/log/php/shutdown.log', Logger::ERROR));
$log->pushHandler(new SlackWebhookHandler('https://hooks.slack.com/services/...', Logger::CRITICAL));

register_shutdown_function(function () use ($log) {
    $error = error_get_last();
    if ($error && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR])) {
        $log->critical('PHP Fatal Error', [
            'message' => $error['message'],
            'file' => $error['file'],
            'line' => $error['line'],
            'trace' => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 5),
            'memory' => memory_get_peak_usage(true),
            'time' => date('c'),
        ]);
    }
});

最佳實踐清單

  • 入口檔案(index.php、cli.php)最早註冊 shutdown handler
  • 區分 CLI/Web SAPI:CLI 直接輸出 stderr,Web 檢查 headers_sent() 再輸出 HTML
  • 記錄完整上下文:請求參數、Session ID、User Agent、記憶體峰值
  • 配合 auto_prepend_file 全域註冊,無需修改每個入口
  • 定期審查 shutdown 日誌,主動發現潛在穩定性問題

掌握 shutdown 機制,是 PHP 應用可觀測性建設的基石。

copyright © 萬盛學電腦網 all rights reserved