Laravel API 认证失败时返回 JSON 错误响应的正确配置

当 laravel api 路由因未认证被拒绝访问时，默认会尝试重定向到 `login` 路由（面向 web），导致 `routenotfoundexception`；只需在请求头中声明 `accept: application/json`，即可触发框架返回标准 json 错误响应（如 401 unauthorized）。

在 Laravel 中，API 认证失败时出现 Route [login] not defined 错误，根本原因在于：Laravel 的 auth:sanctum 中间件默认按“Web”场景处理未认证请求——它会尝试调用 RedirectIfAuthenticated 或生成重定向响应，而该逻辑依赖 route('login')。但在纯 API 场景下，该路由通常未定义（且不应存在），从而抛出异常。

✅ 正确解决方案：确保客户端声明 Accept: application/json

这是最轻量、最符合 Laravel 设计约定的方式。Laravel 内部通过 Request::expectsJson() 判断是否应返回 JSON 响应，而该方法正是检查 Accept 请求头是否包含 application/json。

? Postman 配置示例：

• 方法：GET
• URL：http://your-app.test/api/movies
• Headers → 添加：

  Accept: application/json
  Authorization: Bearer <your-invalid-or-missing-token>

此时，若 Token 缺失、过期或无效，Laravel 将自动返回：

{
  "message": "Unauthenticated."
}

HTTP 状态码为 401 Unauthorized —— 这正是你期望的 JSON 响应。

人民网AIGC-X

国内科研机构联合推出的AI生成内容检测工具

下载

⚠️ 常见误区与补充说明

• ❌ 不要在 api.php 路由文件中手动加 Auth::check() 判断：这无法拦截中间件抛出的异常，且逻辑冗余。
• ❌ 不要重写 AuthController 处理全局认证失败：认证校验发生在中间件层（auth:sanctum），控制器只负责登录/注册。
• ✅ 若需自定义未认证响应内容（如统一结构、添加 code 字段），可全局覆盖 Sanctum 的认证异常响应：

在 app/Exceptions/Handler.php 中重写 unauthenticated() 方法：

use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\JsonResponse;

protected function unauthenticated($request, AuthenticationException $exception): JsonResponse
{
    return response()->json([
        'success' => false,
        'message' => 'Authentication required.',
        'code'    => 'UNAUTHORIZED',
    ], 401);
}

✅ 注意：此方法仅在 Accept: application/json 存在时生效；否则仍可能触发重定向（但 API 客户端绝不应省略该头）。

? 验证你的环境是否就绪

确保已启用 Sanctum 并正确发布配置：

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan sanctum:install

并在 config/auth.php 中确认 api guard 使用 sanctum：

'guards' => [
    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

✅ 总结

遵循此规范，你的 API 将稳定返回语义清晰的 JSON 认证错误，彻底告别 RouteNotFoundException。