线上故障最怕的不是报错,而是"没有报错":页面白屏、接口返回 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 的实例。
| 对比项 | Exception | Error |
|---|---|---|
| 语义 | 业务/运行时异常,调用方可预期 | 引擎级错误,通常意味着代码有 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 永远走不到,属于"静默失效",比报错更难查。
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,会覆盖掉原来的返回值,这个坑非常隐蔽。
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 块、只写一句 // ignore、或者捕获后 return false 却不上报,等于把故障信息永久删除。至少要做到"记录 + 重新抛出"或"记录 + 转为业务错误码"。三、PHP 8 之后值得用的三个语法糖
PHP 8.0 的非捕获 catch(catch without variable)让"只关心类型、不关心对象"的兜底写法更干净;同版本的 throw 表达式 让 ??、箭头函数里也能直接抛异常;PHP 8.0 的 match 则适合把错误码映射成 HTTP 状态码。
// 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 子类做差异化响应。
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)应该注册三个处理器,覆盖"警告类错误""未捕获异常""致命错误"三种情况。
// 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 也没有 rethrow | catch 内 rollBack 并 rethrow |
| 返回值被改写 | finally 里写了 return | finally 只做清理,不返回值 |
| 线上暴露绝对路径 | display_errors 未关闭 | 生产 display_errors=Off,log_errors=On |
@ 抑制符不是错误处理。它只降低错误级别,异常、致命错误照样会中断脚本,还会让日志里出现难以定位的空白记录。七、生产落地清单
把上面这些收敛成五条,基本就能覆盖绝大多数场景:一是所有对外边界(控制器、命令行入口)必须有 catch (Throwable) 兜底,保证返回结构统一;二是业务异常统一继承自建基类,错误码集中管理,禁止随手 throw new \Exception('xx');三是异常只记一次日志,避免每层 catch 都打一条导致日志爆炸;四是日志里必须带 trace_id,与请求链路对齐;五是监控告警按异常类型分级,业务异常走统计、系统异常走告警。
错误处理写得好,最大的收益不是"代码更优雅",而是线上出问题时你有据可查。try/catch 只是语法,真正的工程能力在于:异常发生时,系统仍然按你设计的方式降级、记录、恢复。
相关阅读
- PHP 学习路线图 2026:从入门到进阶的完整指南 —— 把异常处理放在整体学习路径里看,更容易理解它为什么是进阶必修。
- PHP 8.1 vs 8.2 对比与升级教程:动态属性 Error 与 readonly class 实战 —— 动态属性弃用后抛出的正是
Error,与本文的错误分类互为印证。 - PHP 8.4 vs 8.5 对比与升级教程:管道操作符、URI 扩展与 clone with —— 版本升级时异常行为的变化,是回归测试的重点区域。