ThinkPHP 中实现自定义异常捕获需三步：定义继承 Exception 的类（如 BusinessException）、在 Handler.php 的 render() 中 instanceof 判断并返回 JSON 响应、业务层主动 throw 自定义异常；避免 try-catch 替代全局处理，确保状态码、code/msg/data 语义统一。
在 ThinkPHP 中实现自定义异常类的捕获，核心在于统一异常处理机制的接管 + 自定义异常类的注册 + 业务逻辑中主动抛出。这不是简单 try-catch 就能覆盖的，而是要让框架在任何未捕获异常发生时，都能识别你的类型并走你预设的响应逻辑。
定义继承自 Exception 的自定义异常类
这是基础。你需要明确区分异常语义，比如业务异常、参数异常、权限异常等，各自对应不同 HTTP 状态码和错误结构：
- 类名建议带后缀（如 BusinessException），避免与系统异常混淆
- 构造函数可接受 message、code、data（如附加错误字段、trace ID）等参数，便于后续格式化
- 不需要重写 __toString 或其他魔术方法，ThinkPHP 异常处理器会调用 getTraceAsString() 和 getCode()/getMessage() 等标准接口
示例：
namespace app\exception;
class BusinessException extends \Exception
{
protected $data;
public function __construct($message = '', $code = 400, $data = [])
{
parent::__construct($message, $code);
$this->data = $data;
}
public function getData()
{
return $this->data;
}
}
在全局异常处理类中识别并差异化响应
ThinkPHP 6+ 默认使用 app/exception/Handler.php，你需要重写 render() 方法，对自定义异常做特殊处理：
立即学习“PHP免费学习笔记（深入）”；
- 先用 instanceof 判断是否为你的异常类（支持多类型判断，如
$e instanceof BusinessException || $e instanceof ValidateException） - 根据异常类型设置不同的 HTTP 状态码（如 BusinessException → 400，AuthException → 401）
- 返回统一 JSON 响应：包含 code、msg、data（来自异常实例）、timestamp 等字段，保持前后端契约一致
- 注意：不要在 render 中 throw 新异常，否则会二次进入 handler，造成死循环
示例片段：
use app\exception\BusinessException;
public function render($request, Throwable $e): Response
{
if ($e instanceof BusinessException) {
return json([
'code' => $e->getCode(),
'msg' => $e->getMessage(),
'data' => $e->getData(),
'time' => date('Y-m-d H:i:s'),
])->code($e->getCode());
}
// 其他异常走默认逻辑（或记录日志后返回 500）
return parent::render($request, $e);
}
在中间件或控制器中主动抛出自定义异常
捕获的前提是“有东西可捕”。你在业务逻辑中不能只 return false 或 throw new Exception()，而要精准抛出你的类：
- 验证失败？不直接返回错误数组，而是 throw new ValidateException($fail)（TP 已内置，也可继承扩展）
- 用户余额不足？throw new BusinessException('余额不足', 400, ['field' => 'balance'])
- 接口幂等校验失败？throw new BusinessException('请求已被处理', 409)
- 避免在模型层 throw 新异常，推荐在 service 或 controller 层集中抛出，利于维护
补充：配置与调试建议
- 确保 app_debug = true 开发时能看到完整 trace；上线后关闭，靠日志 + 自定义响应体定位问题
- 在 app/exception/Handler.php 的 report() 方法中，可对自定义异常做单独日志记录（如写入 error.log 并标记 level=ERROR）
- 若使用 Swoole 或 Hyperf 风格的长连接场景，需确认异常处理器是否被正确加载（TP8 对 Swoole 支持更原生）
- 前端统一拦截 4xx/5xx 响应，根据 code 字段做 toast 提示或跳转，避免解析 msg 字符串做逻辑判断
