ThinkPHP版本配置模板：自定义异常处理类编写-ThinkPHP-PHP中文网

thinkphp 6/8 自定义异常处理类必须继承 think\exception\handle，render 方法接收 request 和 throwable 参数并返回 response；tp5 的 exceptionhandle 已废弃，版本混淆将导致失效。

thinkphp版本配置模板：自定义异常处理类编写

ThinkPHP 6/8 的自定义异常处理类必须继承 think\exception\Handle，且 render 方法签名含 Request 和 Throwable 两个参数，返回 Response 实例；TP5 则用 think\exception\ExceptionHandle，但已废弃。写错基类或签名，直接静默失效。

确认当前 ThinkPHP 版本再动手

TP6 和 TP8 不兼容 TP5 的异常类写法，TP8 更激进：原生 Exception 被完全绕过，只接管 think\Exception 及其子类。不确认版本就开写，90% 概率白忙活。

运行 php think version 查看输出，明确是 v6.x 还是 v8.x
TP6：类路径默认为 app/exception/Handler.php，需实现 think\contract\ExceptionHandlerInterface（否则配置不生效）
TP8：推荐用 app/exception.php 匿名函数方式注册，更轻量；若用类，必须继承 think\exception\Handle，且不能出现 echo、exit 或未捕获的二次异常
TP5 项目仍在维护？立刻停用 think\exception\ExceptionHandle——该类在 TP6+ 中已删除，类名写错会报 Class not found

`render` 方法里不能干的事

这个方法是框架兜底响应的唯一出口，但约束极严。常见“一写就崩”全是踩了这些坑。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

不能调用 echo、print_r、var_dump —— 输出会混入响应体，破坏 JSON 格式或 HTML 结构
不能手动 header() 或 http_response_code() —— 状态码必须通过 response(...)->code(500) 显式设置，否则中间件可能覆盖
不能在 render 里再抛异常（比如日志写失败又 throw）—— 触发无限递归，最终白屏或 500
不能对所有异常走同一逻辑：比如把 ValidateException 和数据库连接异常都返回 500，前端无法区分是参数错还是服务挂了
TP8 下尤其注意：不能用 new Exception() 测试，必须用 new \think\exception\HttpException(400, 'xxx') 才能进 render

业务异常要封装成独立类，别塞进 `render`

把 code、message、httpCode 全塞进 render 的 if 分支里，后期维护会疯。正确做法是让业务异常自己携带元信息。

新建 app/exception/BusinessException.php，继承 \think\Exception
构造函数接收 $code（业务码，如 1002）、$message、$httpCode = 400，全部存入父类属性
控制器中统一用 throw new BusinessException(1002, '手机号格式错误', 400)，而不是 return json(['code'=>1002])
render 里只做判断：if ($e instanceof BusinessException) { return response()->json([...], $e->getHttpCode()); }
避免暴露数据库原生错误码：MySQL 的 1062（唯一键冲突）应映射为业务码 2005（手机号已注册），不能直接透出

配置项不生效？先清缓存再查三处硬伤

TP6/8 默认缓存配置，改完 config/exception.php 或 config/app.php 后不清理，等于没改。

执行 php think clear:config，不是 clear:runtime，后者清不掉配置缓存
检查 config/exception.php 中的键名是不是 handle（不是 handler、exception_handler）
确认类文件命名空间与路径严格匹配：类声明 namespace app\exception; → 文件必须是 app/exception/Handler.php
TP8 多应用下，检查的是对应应用目录下的 config/exception.php，不是根目录的
临时加一行 file_put_contents(RUNTIME_PATH.'render_test.log', 'hit', FILE_APPEND); 到 render 开头，访问接口后看日志是否生成，快速验证是否真进来了