Laravel 9中如何验证Sanctum令牌有效性及排查异常响应问题

1. 确认API Guard配置 #

检查config/auth.php中的API guard驱动是否匹配你使用的令牌类型（如原生Token、Sanctum或Passport）：

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'token', // 若用Sanctum则改为'sanctum'，Passport则改为'passport'
        'provider' => 'users',
        'hash' => false,
    ],
],

2. 自定义认证异常处理 #

Laravel默认的AuthenticationException会针对Web请求返回重定向HTML，需修改异常处理器，让API请求返回JSON格式响应：

修改app/Exceptions/Handler.php，添加API异常渲染逻辑：

use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;

public function register()
{
    $this->renderable(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '令牌无效或已过期',
                'status' => 401
            ], 401);
        }
    });
}

3. 确保API路由使用正确中间件 #

在routes/api.php中，为路由绑定正确的认证中间件，或自定义令牌验证中间件：

方式一：使用官方auth:api中间件 #

Route::middleware('auth:api')->group(function () {
    Route::get('/check-token', function () {
        return response()->json([
            'message' => '令牌有效',
            'status' => 200
        ]);
    });
});

方式二：自定义令牌验证中间件 #

创建app/Http/Middleware/CheckTokenValidity.php：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class CheckTokenValidity
{
    public function handle(Request $request, Closure $next)
    {
        if (!Auth::guard('api')->check()) {
            return response()->json([
                'message' => '令牌无效或已过期',
                'status' => 401
            ], 401);
        }

        return $next($request);
    }
}

在app/Http/Kernel.php注册中间件：

protected $routeMiddleware = [
    // ...
    'check.token' => \App\Http\Middleware\CheckTokenValidity::class,
];

在API路由中使用：

Route::middleware('check.token')->get('/check-token', function () {
    return response()->json([
        'message' => '令牌有效',
        'status' => 200
    ]);
});

4. 检查Postman请求头配置 #

确保请求头符合令牌验证要求：

• 原生Token驱动：Authorization: Bearer {你的令牌} 或 X-API-TOKEN: {你的令牌}（对应config/auth.php中API guard的input_key配置）
• Sanctum/Passport：Authorization: Bearer {你的令牌}

5. 排除API路由的CSRF验证 #

在app/Http/Middleware/VerifyCsrfToken.php中添加API路由排除规则：

protected $except = [
    'api/*',
];

内容的提问来源于stack exchange，提问作者ayaashraf