PHP 自定义错误处理程序

Begindev 编辑部 March 25, 2026

PHP 默认的错误处理机制在构建健壮的应用程序时往往显得捉襟见肘。自定义错误处理程序（Custom error handlers）提供了一种拦截 PHP 错误和异常的方法，允许你定制响应策略，比如：记录详细的日志信息、展示对用户友好的提示页面，甚至尝试从某些错误状态中恢复。这让开发者能够集中管理错误、提升应用的容错能力，并提供更一致的用户体验。

1. 注册自定义错误处理程序

PHP 提供了 set_error_handler() 函数，用于注册一个用户自定义的函数。在脚本执行期间触发的所有错误都将交由该函数处理。

⚠️ 注意： 以下级别的严重错误无法被接管：E_ERROR、E_PARSE、E_CORE_ERROR、E_CORE_WARNING、E_COMPILE_ERROR、E_COMPILE_WARNING，以及大多数在调用 set_error_handler() 的同一个文件中发生的 E_STRICT 错误。这些致命错误通常会导致脚本直接终止，无法被优雅地处理。

你的自定义错误处理函数必须至少接收两个参数：

int $errno: 触发的错误级别（数字）。
string $errstr: 错误描述信息。

它还可以选择性地接收另外三个参数以获取更丰富的上下文：
3. string $errfile: 发生错误的文件名。
4. int $errline: 发生错误的行号。
5. array $errcontext: 一个指向错误发生时活动符号表的数组（包含了当时的变量状态）。

返回值机制：

如果你的函数返回 true，PHP 标准的错误处理程序将被绕过。
如果返回 false（或不返回任何内容/返回 null），在你的自定义函数执行完毕后，PHP 标准的错误处理程序仍会继续执行。

<?php
// 1. 定义自定义错误处理函数
function myCustomErrorHandler(int $errno, string $errstr, ?string $errfile = null, ?int $errline = null, ?array $errcontext = null) {
    // 将错误编号转换为人类可读的类型
    $errorType = "未知错误";
    switch ($errno) {
        case E_USER_ERROR:    $errorType = "用户级致命错误"; break;
        case E_USER_WARNING:  $errorType = "用户级警告"; break;
        case E_USER_NOTICE:   $errorType = "用户级通知"; break;
        case E_WARNING:       $errorType = "系统警告"; break;
        case E_NOTICE:        $errorType = "系统通知"; break;
        case E_DEPRECATED:    $errorType = "废弃特性警告"; break;
        default:              $errorType = "系统错误 (级别: " . $errno . ")"; break;
    }

    // 2. 准备用于记录日志的详细信息
    $logMessage = "[" . date("Y-m-d H:i:s") . "] " . $errorType . ": " . $errstr;
    if ($errfile) $logMessage .= " 发生在文件 " . $errfile;
    if ($errline) $logMessage .= " 第 " . $errline . " 行";
    $logMessage .= PHP_EOL;

    // (通常你会在这里将 $logMessage 写入日志文件，例如使用 error_log)

    // 3. 根据错误级别决定如何在页面上展示
    if ($errno === E_USER_ERROR) { 
        echo "<div style='color: red; border: 1px solid red; padding: 10px;'>";
        echo "<h1>发生了一个意外错误。</h1>";
        echo "<p>给您带来不便，我们深表歉意。我们的团队已收到通知。</p>";
        echo "</div>";
        // 致命错误通常需要中断脚本
        exit(1); 
    } else {
        // 对于警告和通知，我们只在开启了 display_errors 的情况下显示它们
        if (ini_get('display_errors')) { 
            echo "<p style='color: orange;'><strong>" . $errorType . ":</strong> " . $errstr . "</p>";
        }
    }

    // 4. 返回 true 阻止 PHP 默认的错误输出，实现完全接管
    return true;
}

// 注册我们的自定义函数
set_error_handler("myCustomErrorHandler");

// 触发测试：
trigger_error("这是一个自定义的用户生成的警告。", E_USER_WARNING);

echo "尝试执行除以零的操作...<br>";
$result = 10 / 0; // 这将触发一个原生的 E_WARNING，并被我们的函数捕获
echo "错误处理完毕，脚本继续执行。<br>";

// 如果你想恢复使用 PHP 默认的错误处理程序：
// restore_error_handler();
?>

在这个例子中，无论是手动通过 trigger_error() 触发的错误，还是原生代码（如除以零）引发的 E_WARNING，都由 myCustomErrorHandler 全权接管。

2. 处理可捕获的致命错误 (E_RECOVERABLE_ERROR)

虽然 set_error_handler() 抓不到 E_ERROR，但它可以捕捉到 E_RECOVERABLE_ERROR。这类错误如果不加干预，通常也会导致脚本终止，但 PHP 给了我们一次“挽救”的机会。一个典型的触发场景是：当启用了严格类型检查 (declare(strict_types=1)) 时，向函数传递了错误类型的参数。

<?php
declare(strict_types=1); // 开启严格类型检查

function myRecoverableErrorHandler(int $errno, string $errstr, ?string $errfile = null, ?int $errline = null, ?array $errcontext = null) {
    echo "<div style='background-color: #ffeeee; border: 1px solid red; padding: 10px;'>";
    echo "<h3>拦截到可恢复的致命错误！</h3>";
    echo "<p><strong>信息:</strong> " . htmlspecialchars($errstr) . "</p>";
    echo "<p>尝试让脚本优雅地继续执行...</p>";
    echo "</div>";
    
    // 记录日志...
    return true; // 阻止 PHP 默认的致命错误行为
}

set_error_handler("myRecoverableErrorHandler");

function greet(string $name): string {
    return "你好，" . $name . "！";
}

echo greet("Alice") . "<br>";

// 下面这行会触发 E_RECOVERABLE_ERROR，因为 greet 期望 string，但传入了 int
echo greet(123) . "<br>"; 

echo "由于我们拦截了错误，脚本坚强地活了下来并继续执行。<br>";
?>

如果没有我们自定义的 Handler，传入整数 123 将直接导致 Fatal Error 并让页面崩溃。通过自定义 Handler，我们不仅拦截并记录了错误，还使得应用程序更具弹性（Resilient）。

3. 企业级应用策略

3.1 区分开发与生产环境

错误报告的策略在开发环境和生产环境中应当有天壤之别。在开发中，你需要立即看到所有详细的报错；而在生产环境中，你应当静默地记录日志，并向用户展示一个友好的通用错误页面，防止敏感路径信息泄露。

<?php
define('APP_ENV', 'production'); // 假设当前是生产环境

function masterErrorHandler(int $errno, string $errstr, ?string $errfile = null, ?int $errline = null) {
    // 1. 无论什么环境，都先记录详细日志
    $logMsg = date("[Y-m-d H:i:s]") . " [$errno] $errstr in $errfile:$errline" . PHP_EOL;
    error_log($logMsg, 3, "/var/log/my_app_errors.log");

    // 2. 根据环境决定显示策略
    if (APP_ENV === 'development') {
        // 开发环境：直接将详细信息甩在屏幕上
        echo "<pre style='background:#f4f4f4; border:1px solid #ccc; padding:10px;'>";
        echo "<b>🔥 DEVELOPMENT ERROR:</b>\n$logMsg</pre>";
    } else {
        // 生产环境：针对严重错误，清理输出缓冲并显示友好的 500 页面
        if ($errno === E_USER_ERROR || $errno === E_RECOVERABLE_ERROR) {
            ob_clean(); // 清空之前可能输出了一半的乱码页面
            include 'friendly_500_error_page.html';
            exit(1);
        }
    }
    return true;
}

set_error_handler("masterErrorHandler");
?>

3.2 终极融合：将传统错误转换为异常 (Exceptions)

传统的 PHP 错误（Errors）和现代的面向对象异常（Exceptions）是两套独立的系统。为了统一管理，业界最推崇的最佳实践是：在自定义错误处理程序中，将所有捕获到的传统错误，统统包装成 ErrorException 对象抛出。

这样，你就可以在整个项目中统一使用 try...catch 块来捕获所有类型的问题！

<?php
// 定义一个将 Error 转换为 Exception 的处理程序
function exceptionOnErrorHandler(int $errno, string $errstr, ?string $errfile = null, ?int $errline = null) {
    // 尊重 error_reporting 的设置，被忽略的级别不抛出异常
    if (!(error_reporting() & $errno)) {
        return false; 
    }
    // 将错误打包成 ErrorException 抛出
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}

// 注册转换器
set_error_handler("exceptionOnErrorHandler");

// 现在，你可以用处理异常的方式来处理传统的 PHP 警告了！
try {
    echo "尝试除以零...<br>";
    $result = 10 / 0; // 这个原生的 E_WARNING 现在会变成一个被抛出的 Exception
    
} catch (ErrorException $e) {
    echo "<div style='color: blue; padding: 10px; border: 1px solid blue;'>";
    echo "<h3>🎉 成功捕获 ErrorException (由 PHP 警告转化而来)！</h3>";
    echo "描述：" . $e->getMessage();
    echo "</div>";
}
?>

这种策略极大地简化了应用程序整体的错误流控制，是现代 PHP 框架（如 Laravel, Symfony）底层错误处理机制的核心原理。