当 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 响应。
⚠️ 常见误区与补充说明
- ❌ 不要在 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 请求必须携带 Accept: application/json 请求头 |
| 无需修改路由或控制器 | auth:sanctum 中间件原生支持 JSON 响应，前提是请求头明确声明 |
| 调试建议 | 在 Postman / curl 中始终检查请求头；避免使用浏览器直接访问 /api/movies（浏览器不发 Accept: application/json） |
| 进阶定制 | 通过 Handler.php 的 unauthenticated() 方法统一响应格式 |
遵循此规范，你的 API 将稳定返回语义清晰的 JSON 认证错误，彻底告别 RouteNotFoundException。
