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

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

在 laravel 中，API 认证失败时出现 Route

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 

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

{   "message": "Unauthenticated." }

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

⚠️ 常见误区与补充说明

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

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

use IlluminateAuthAuthenticationException; use IlluminateHttpJsonResponse;  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="LaravelSanctumSanctumServiceProvider" php artisan sanctum:install

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

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

✅ 总结

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