线上故障最怕的不是报错,而是"没有报错":页面白屏、接口返回 500、日志里却干干净净,只能靠猜。把 PHP 异常处理写成一套体系,而不是随手加几个 try...catch,是每个 PHP 项目从"能跑"走向"可维护"的必经一步。本文从 PHP 7 引入的 Throwable 统一体系讲起,把 try/catch/finally、Error 与 Exception 的区别、自定义业务异常、三个全局兜底处理器串成一条完整链路,最后给出可以直接照抄的生产落地清单。

一、先分清:Error 和 Exception 是兄弟,不是父子

PHP 5 时代的痛点很明确:Fatal error 属于引擎级错误,try/catch 根本抓不到,只能靠 register_shutdown_function 事后捞尸体。PHP 7 之后官方把两者收拢到同一个接口 Throwable 之下,Exception 和 Error 是它的两个并列实现,任何 throw 出来的东西都必须是 Throwable 的实例。

对比项ExceptionError
语义业务/运行时异常,调用方可预期引擎级错误,通常意味着代码有 bug
典型场景参数非法、余额不足、第三方接口超时类型不匹配、调用未定义方法、除零、内存耗尽
是否能恢复多数可以,业务上需要专门处理一般不应吞掉,交给上层记录并终止
捕获方式都能被 catch (Throwable $e) 捕获;catch (Exception $e) 抓不到 Error
ℹ️
记住这一条就够了
只想写一处兜底时,用 catch (Throwable $e);想精确处理业务分支时,按具体异常类分别 catch。写 catch (Exception $e) 却抱怨"TypeError 没被捕获",是 PHP 7 之后最常见的新手问题。

二、try/catch/finally 的三个易错点

1. catch 的顺序:子类必须写在父类前面

PHP 的 catch 匹配是自上而下、命中即停。如果先写 catch (Throwable $e),后面针对具体异常的 catch 永远走不到,属于"静默失效",比报错更难查。

php order.php
try {
    $order = $service->create($payload);
} catch (InsufficientBalanceException $e) {
    // 最具体的放最前:可以直接给用户看的业务提示
    return response()->json(['code' => 4001, 'msg' => $e->getMessage()], 400);
} catch (PaymentException $e) {
    // 支付域的统一异常:记日志 + 走重试队列
    Log::warning('payment failed', ['order' => $payload['sn']]);
    $retry->push($payload);
} catch (Throwable $e) {
    // 最后兜底:Error 与未预料的 Exception 都落在这里
    Log::error('unexpected', ['ex' => $e]);
    return response()->json(['code' => 500, 'msg' => '系统繁忙'], 500);
}

2. finally 一定会执行,包括 return 之后、异常继续抛出之前

finally 适合放释放资源、关闭事务、还原上下文这类动作。它甚至会在 return 已经算出返回值之后执行——但要注意,如果 finally 里自己写了 return,会覆盖掉原来的返回值,这个坑非常隐蔽。

php transaction.php
public function transfer(int $from, int $to, int $amount): void
{
    $this->db->beginTransaction();
    try {
        $this->debit($from, $amount);
        $this->credit($to, $amount);
        $this->db->commit();
    } catch (Throwable $e) {
        $this->db->rollBack();   // 任何异常都回滚
        throw $e;               // 不要吞掉,交给上层决定
    }
    // 这里不需要再写 finally,commit/rollBack 已覆盖全部分支
}
⚠️
不要用 catch 吞掉异常
空的 catch 块、只写一句 // ignore、或者捕获后 return false 却不上报,等于把故障信息永久删除。至少要做到"记录 + 重新抛出"或"记录 + 转为业务错误码"。

三、PHP 8 之后值得用的三个语法糖

PHP 8.0 的非捕获 catch(catch without variable)让"只关心类型、不关心对象"的兜底写法更干净;同版本的 throw 表达式 让 ??、箭头函数里也能直接抛异常;PHP 8.0 的 match 则适合把错误码映射成 HTTP 状态码。

php handler.php
// 1. 非捕获 catch:不关心异常对象时省略变量
try {
    $json = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    throw new InvalidArgumentException('响应不是合法 JSON');
}

// 2. throw 表达式:可以直接出现在 ?? 右侧
$config = $userConfig ?? throw new RuntimeException('配置缺失');

// 3. match 做异常到状态码的映射
$status = match (true) {
    $e instanceof InvalidArgumentException => 422,
    $e instanceof AuthException            => 401,
    $e instanceof NotFoundException        => 404,
    default                                => 500,
};

四、自定义异常:让异常携带业务语义

原生 \Exception 只有 message 和 code,业务上往往还需要错误码、上下文字段、以及"是否可重试"这类标记。建议按领域建一个基类,再派生具体异常,这样上层可以只 catch 基类做统一处理,也可以精确 catch 子类做差异化响应。

php AppException.php
namespace App\Exception;

class AppException extends \RuntimeException
{
    public function __construct(
        string $message,
        private readonly int $bizCode = 0,
        private readonly array $context = [],
        private readonly bool $retryable = false,
        ?\Throwable $previous = null
    ) {
        parent::__construct($message, $bizCode, $previous);
    }

    public function bizCode(): int { return $this->bizCode; }
    public function context(): array { return $this->context; }
    public function isRetryable(): bool { return $this->retryable; }

    // 统一转成对外的错误结构,避免把栈信息泄露给前端
    public function toArray(): array
    {
        return ['code' => $this->bizCode, 'msg' => $this->getMessage()];
    }
}

// 具体异常只负责语义
final class InsufficientBalanceException extends AppException
{
    public function __construct(float $need, float $have)
    {
        parent::__construct(
            sprintf('余额不足,需要 %.2f,当前 %.2f', $need, $have),
            bizCode: 4001,
            context: ['need' => $need, 'have' => $have]
        );
    }
}

有了 previous 参数,还能保留异常链:底层抛出的 PDOException 被包装成业务异常时,原始栈信息不会丢,排查时用 $e->getPrevious() 就能一层层往上追。

五、三个全局兜底:把漏网之鱼收干净

再规范的代码也会有漏写 try 的地方。生产入口(如 public/index.php 或框架的 bootstrap)应该注册三个处理器,覆盖"警告类错误""未捕获异常""致命错误"三种情况。

php bootstrap.php
// 1. 把 warning / notice 转成异常,避免"静默失败"
set_error_handler(function (int $no, string $str, string $file, int $line): bool {
    if (!(error_reporting() & $no)) {
        return false;              // 被 @ 抑制的错误交还给 PHP
    }
    throw new \ErrorException($str, 0, $no, $file, $line);
});

// 2. 未捕获异常:记日志 + 输出友好页面
set_exception_handler(function (\Throwable $e): void {
    error_log(sprintf("[uncaught] %s: %s in %s:%d\n%s",
        get_class($e), $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString()));

    if (!headers_sent()) {
        http_response_code(500);
    }
    include __DIR__ . '/views/500.php';   // 生产环境不输出栈
    exit(1);
});

// 3. 致命错误(内存超限、解析失败等)只能靠 shutdown 兜底
register_shutdown_function(function (): void {
    $err = error_get_last();
    if ($err && in_array($err['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR], true)) {
        error_log(sprintf("[fatal] %s in %s:%d", $err['message'], $err['file'], $err['line']));
    }
});
✅
顺序有讲究
这三个处理器要尽早注册,且必须在框架初始化之前——否则框架自己的错误处理会先接管,你注册的只是"第二顺位"。

六、几个反复踩的坑

现象原因正确做法
TypeError 抓不到写成了 catch (Exception $e)改为 catch (Throwable $e)
后面的 catch 永不执行父类异常写在子类前面由具体到宽泛排列
事务没回滚异常被 catch 后没有 rollBack 也没有 rethrowcatch 内 rollBack 并 rethrow
返回值被改写finally 里写了 returnfinally 只做清理,不返回值
线上暴露绝对路径display_errors 未关闭生产 display_errors=Off,log_errors=On
⚠️ 注意:@ 抑制符不是错误处理。它只降低错误级别,异常、致命错误照样会中断脚本,还会让日志里出现难以定位的空白记录。

七、生产落地清单

把上面这些收敛成五条,基本就能覆盖绝大多数场景:一是所有对外边界(控制器、命令行入口)必须有 catch (Throwable) 兜底,保证返回结构统一;二是业务异常统一继承自建基类,错误码集中管理,禁止随手 throw new \Exception('xx');三是异常只记一次日志,避免每层 catch 都打一条导致日志爆炸;四是日志里必须带 trace_id,与请求链路对齐;五是监控告警按异常类型分级,业务异常走统计、系统异常走告警。

错误处理写得好,最大的收益不是"代码更优雅",而是线上出问题时你有据可查。try/catch 只是语法,真正的工程能力在于:异常发生时,系统仍然按你设计的方式降级、记录、恢复。

相关阅读