Laravel API中Sanctum认证失败时返回JSON的实现方法

默认情况下，当auth:sanctum中间件认证失败时，Laravel可能会返回登录视图而非JSON响应，这是框架异常处理逻辑的默认行为。要让API路由组在认证失败时返回JSON格式响应，可通过以下方案实现：

方法一：修改全局异常处理器（推荐） #

这是最简洁的方案，通过拦截认证异常并针对API请求返回JSON响应：

1. 打开项目根目录下的app/Exceptions/Handler.php文件
2. 在文件顶部导入认证异常类：

use Illuminate\Auth\AuthenticationException;

3. 在render方法中添加异常拦截逻辑：

public function render($request, Throwable $e)
{
    // 当认证失败且请求需要JSON响应时，返回自定义JSON
    if ($e instanceof AuthenticationException && $request->wantsJson()) {
        return response()->json([
            'message' => '身份认证失败，请提供有效令牌',
            'status_code' => 401
        ], 401);
    }

    return parent::render($request, $e);
}

补充说明： #

• $request->wantsJson()会自动识别两类请求：
  • 请求头包含Accept: application/json的请求
  • 带有X-Requested-With: XMLHttpRequest头的AJAX请求
• 若你的API路由统一使用/api前缀，也可以用$request->is('api/*')替代$request->wantsJson()，实现更精准的路由匹配

方法二：自定义Sanctum认证中间件（可选） #

如果不想修改全局异常处理器，可自定义中间件覆盖默认认证失败逻辑：

1. 创建自定义中间件：

php artisan make:middleware SanctumApiAuth

2. 在app/Http/Middleware/SanctumApiAuth.php中编写认证逻辑：

<?php

namespace App\Http\Middleware;

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

class SanctumApiAuth
{
    public function handle($request, Closure $next)
    {
        if (!Auth::guard('sanctum')->check()) {
            return response()->json([
                'message' => '身份认证失败'
            ], 401);
        }

        return $next($request);
    }
}

3. 在app/Http/Kernel.php的$routeMiddleware数组中注册中间件：

protected $routeMiddleware = [
    // ...其他已注册中间件
    'auth.sanctum.api' => \App\Http\Middleware\SanctumApiAuth::class,
];

4. 在api.php中使用自定义中间件替代原auth:sanctum：

Route::middleware('auth.sanctum.api')->group(function () {
    // 你的受保护API路由
});

验证效果 #

向受保护的API路由发送未携带有效Sanctum令牌的请求，此时会返回你定义的JSON响应，而非默认的登录视图。

内容的提问来源于stack exchange，提问作者José Vicente López Delgadillo