You need to enable JavaScript to run this app. Laravel Passport中如何检查access token是否过期并返回专属响应?
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.12 20:27:04