ThinkPHP 8.0 优雅地定义全局异常处理 Handler【报错】

ThinkPHP 8.0 的全局异常处理机制已经彻底重构。如果你发现自定义 Handler 不生效、报错甚至直接显示空白页，别急着怀疑代码写错了——大概率是因为还在沿用 TP6 或更早版本的那套配置习惯，而新框架已经完全不认 config/app.php 里的 exception_handle 了，并且不报错、不提示，直接静默回退到默认行为。核心要点可以概括为：必须通过服务提供者注册，不能再用配置文件；render() 方法签名和返回值有硬性要求；report() 必须调用父类；CLI 环境还需要额外手动绑定。

下面逐一拆解容易踩的坑，以及正确的做法。

必须用服务提供者注册，不能配 config/app.php

TP8 已经把 config/app.php 中 exception_handle 或 app_exception 的支持彻底移除。你在那个文件里写了任何异常处理器类路径，框架启动时根本不会读取，也不会报错，只会用内置处理器兜底。很多开发者在这上面浪费了不少时间——写完代码刷新页面，发现错误还是默认的调试页面。

正确的做法是在 app/provider.php 中返回绑定关系：

return [
    'think\exception\Handle' => app\exception\Handler::class,
];

这里有几个关键点要注意：类必须实现 think\contract\ExceptionHandlerInterface，不能只继承 think\exception\Handle。命名空间和文件路径必须严格一致，比如 app\exception\Handler 就对应 app/exception/Handler.php。要是路径对不上，框架不会自动加载，同样静默失败。

render() 方法签名和返回值有硬性要求

TP8 强制要求 render() 接收 Request 实例并返回 Response 对象，否则会导致二次渲染、混入 HTML 模板，甚至返回空白响应。这个问题在 API 项目中尤其常见——明明想返回 JSON，结果拿到的是奇怪的 HTML 片段。

方法签名必须是：

public function render(Request $request, Throwable $e): Response

不能省略 Request 参数，也不能用 app('request') 来替代。返回时必须显式使用 response()、json() 或 view() 生成的 Response 实例。例如 API 场景可以这样写：

return json(['code' => -1, 'msg' => $e->getMessage()], 500);

切记不要用 echo、die、exit 或直接返回字符串，这些都算无效返回，框架不会按预期处理。

report() 必须调用父类方法，否则日志全丢

很多开发者重写 report() 后只做了钉钉通知或自定义记录，却忘了调用 parent::report($exception)。结果导致 Sentry、日志通道、SQL 错误统计、$ignoreReport 过滤功能全部失效。尤其当你需要依赖框架内置的日志系统时，这个问题特别隐蔽。

基础写法必须包含这一行：

parent::report($exception);

如果需要精简堆栈信息，应该先处理再调用父类：

$trace = array_slice($e->getTrace(), 0, 10);
// 之后调用 parent::report($exception);

同时要注意敏感信息过滤，比如 $_POST、Authorization 头应该在日志写入前清理掉，避免泄露。如果项目并发较高，推荐使用异步写日志的方式，比如 Log::channel('daily')->error(...)，避免阻塞主流程。

CLI 环境要手动绑定，Web 和命令行不共享配置

运行 php think run、单元测试或者任何命令行任务时，框架不会自动加载 app/provider.php 中的绑定，也不会读取 config/app.php 中的异常配置。所以你看到的仍然是原生 PHP 错误堆栈，自定义 Handler 根本不会生效。

解决办法是在命令入口文件（通常是项目根目录下的 think 文件）顶部手动绑定：

App::bind('think\exception\Handle', app\exception\Handler::class);

如果使用了多应用模式（APP_MULTI = true），每个子应用都需单独配置对应的 app/provider.php。验证是否生效的方法很简单：在命令行中抛一个未捕获的异常，看程序是否进入你的 report() 方法进行处理。