PHP自定义异常处理与错误日志记录实战

花开有时

发布时间：2026-10-15 | 3人浏览过

原创

在 PHP 项目开发中，默认的错误输出会泄露敏感路径信息且不够友好。本文将介绍如何结合 set_error_handler 与 register_shutdown_function 构建一套完整的错误监控方案，既能将非致命警告记录至日志文件，又能拦截导致脚本中断的致命错误。

核心功能与目标

默认的 PHP 错误提示包含服务器路径、变量名等敏感信息，不利于生产环境安全。通过自定义错误处理流程，可以实现以下目标：

格式化输出：统一错误信息的格式，便于后续日志分析或 API 返回。
日志持久化：将错误详情（时间、URI、文件、行号）写入文本或数据库。
异常兜底：捕获常规 handler 无法处理的致命错误（Fatal Error），防止脚本静默终止。

完整操作顺序

第1步：初始化环境与注册回调

首先，关闭 PHP 内部默认的严格错误报告模式，防止原始错误信息直接输出到页面。接着，注册两个关键回调函数：errorHandler 用于处理 E_WARNING 等低级错误；fatalErrorHandler 用于脚本结束时兜底。

<?php
// 1. 禁止显示 PHP 内部错误
error_reporting(0);

// 2. 设置常规错误处理器
set_error_handler('errorHandler');

// 3. 注册关机函数，用于捕获致命错误
register_shutdown_function('fatalErrorHandler');

// ... 后续定义类与方法 ...

第2步：编写常规错误日志记录逻辑

自定义的 errorHandler 接收标准的五个参数。在此函数中，我们将提取错误类型、消息、文件路径及行号，将其组装为特定格式的字符串并追加写入日志文件。这种格式清晰的时间+内容结构有助于排查问题。

function errorHandler($errno, $errstr, $errfile, $errline) {
    $arr = array(
        '[' . date('Y-m-d h-i-s') . ']',   // 发生时间
        $_SERVER['REQUEST_URI'],             // 请求 URI (可选)
        '|',                                // 分隔符
        $errstr,                            // 错误消息
        ' in ',                             // 连接词
        $errfile,                           // 出错文件
        ' line: ' . $errline                // 行号
    );
    
    // 拼接成一行日志，追加写入 test.txt
    // 注意：实际生产中建议使用 Monolog 等库替代原生 error_log
    $logContent = implode(' ', $arr) . "\r\n";
    
    // 同步输出到屏幕调试，也可仅记录
    echo $logContent;
    
    // 记录到文件
    error_log($logContent, 3, './test.txt');
}

第3步：实现致命错误（Fatal Error）拦截

set_error_handler 无法捕获 E_ERROR、E_PARSE 等致命错误。当这类错误发生时，脚本会立即终止。我们可以利用 register_shutdown_function 注册的回调来检查最后发生的错误。如果存在致命错误，手动调用 errorHandler 进行统一记录。

function fatalErrorHandler() {
    $e = error_get_last(); // 获取最后一条错误信息
    
    if ($e && in_array($e['type'], [
        E_ERROR,
        E_PARSE,
        E_CORE_ERROR,
        E_COMPILE_ERROR,
        E_USER_ERROR
    ])) {
        // 复用上面的 errorHandler 进行处理和记录
        errorHandler($e['type'], $e['message'], $e['file'], $e['line']);
    }
}

第4步：触发测试与验证结果

为了验证上述机制，我们在代码中故意制造两种类型的错误： 1. **普通警告**：引用未定义的变量。
2. **致命错误**：实例化一个不存在的类。

class Test{
    public function index(){
        // 触发 Warning: Undefined variable
        echo $undefinedVarible;
    }
}

$test = new Test();
$test->index(); // 此处触发 errorHandler

// 制造致命错误
$tesdt = new Tesdt(); // 类名拼写错误
$tesdt->index();      // 此处触发 Fatal Error -> fatalErrorHandler

运行该脚本后，您将看到控制台输出了经过格式化的日志信息，并在 ./test.txt 中保存了完整的错误记录，包括对致命错误的成功捕获。

完成判断与注意事项

确认修改是否生效的标准如下：

视觉隔离：页面上不再出现杂乱的 PHP 警告弹窗，仅显示自定义的格式化信息（调试阶段）或无信息（生产阶段）。
日志文件：./test.txt 文件应更新，且包含对应时间的错误日志条目。
完整性：即使发生致命错误，日志文件中也应包含该致命错误的详细记录。

风险提示：在生产环境中，务必确保 error_reporting(0) 生效，并且不要在 echo 中直接输出敏感路径。建议将 $errfile 替换为相对路径或使用哈希值混淆文件名，同时考虑使用第三方日志库（如 Monolog）替代原生 file_put_contents，以获得更好的并发性能和结构化数据支持。