Laravel Passport中如何检查access token是否过期并返回专属响应?
需求场景
使用Laravel Passport做接口鉴权时,auth:api中间件默认会把所有认证失败的情况统一返回{"message": "unauthenticated"}的401响应,无法区分无效token和过期token两种不同场景,需要为过期token定制单独的返回内容。
当前已完成的配置
受保护接口的路由定义如下:
Route::middleware('auth:api')->post('/test', [TestController::class, 'index']);
实现方案
不需要改动Passport核心源码,只需要在全局异常处理逻辑里识别对应异常类型,定制返回值即可:
- 打开项目的异常处理器文件,低版本Laravel路径为
app/Exceptions/Handler.php,Laravel 11+版本可直接在bootstrap/app.php的异常配置段写自定义逻辑 - 捕获Passport鉴权抛出的OAuth2异常,从异常的前置错误信息里判断是否为token过期场景
- 匹配到过期场景时,直接返回自定义格式的JSON响应,其余认证失败场景沿用默认的
unauthenticated返回即可
参考实现代码(Laravel 10及更早版本)
在app/Exceptions/Handler.php的render方法中追加判断逻辑:
public function render($request, Throwable $exception) { // 仅处理API接口的鉴权异常 if ($request->is('api/*') && $exception instanceof \League\OAuth2\Server\Exception\OAuthServerException) { // 提取JWT校验的违规原因,匹配过期场景 $previousError = $exception->getPrevious(); if ($previousError instanceof \Lcobucci\JWT\Validation\RequiredConstraintsViolated) { $violationMessages = array_map(fn($v) => $v->getMessage(), $previousError->getViolations()); if (in_array('The token expired', $violationMessages)) { return response()->json([ 'message' => 'token expired' ], 401); } } } return parent::render($request, $exception); }
注意事项
- 不要把所有401响应都改写为过期提示,只匹配明确的JWT过期校验错误,避免把token篡改、格式错误等场景误判为过期
- 调试时可以先打印捕获到的异常详情,确认当前Passport版本对应的过期异常提示文案,避免因版本差异导致字符串匹配失效
内容的提问来源于stack exchange,提问作者Saul Montilla
相关产品推荐
相关产品推荐

