jwt多用户场景下过期令牌拦截返回不统一，本质是未按guard类型区分异常处理，需在handler.php中根据users/admins/api_clients等guard分别返回对应错误码与提示，并手动添加cors头、提供refresh指引，禁用默认重定向。
JWT 多用户场景下，过期令牌拦截返回不统一，本质是未区分用户类型做精细化异常处理，导致所有过期请求都走默认 401 或 HTML 页面跳转，破坏 API 一致性。核心在于：Laravel 默认 JWT 异常处理器不感知 guard 差异，也不区分 user/admin/api 等多模型用户体系。
按 guard 类型分离异常响应
JWT 过期（TokenExpiredException）和无效（TokenInvalidException）等异常，在多 guard 场景（如 users、admins、api_clients）中应返回对应语义的错误码与提示，而非全部归为 “Unauthorized”。
- 在
app/Exceptions/Handler.php的render()方法中，先判断请求所属 guard： - 用
$request->route()?->middleware()或$request->is('admin/*')/$request->is('api/*')匹配路径前缀 - 或更可靠地：从中间件链提取 guard 名称，例如检查是否启用了
jwt.auth:admin或jwt.auth:api - 对不同 guard 的 TokenExpiredException 分别返回：
• admins guard → code: 40102, message: "管理员会话已失效，请重新验证身份"
• api_clients guard → code: 40103, message: "API 凭据已过期，请刷新 access_token"
避免中间件提前终止导致 CORS 缺失
JWT 过期时，jwt.auth 中间件抛出异常后直接中断流程，CORS 头不会写入响应——前端看到的是跨域错误而非真实业务错误。
- 不能依赖全局 CORS 中间件兜底，因为异常发生时中间件链已退出
- 必须在
Handler.php的render()中，对所有 JWT 相关异常手动添加头： return $response->header('Access-Control-Allow-Origin', '*')->header('Access-Control-Allow-Headers', 'Authorization, Content-Type');- 若需支持 credentials，还需加
Access-Control-Allow-Credentials: true，并确保config/cors.php中'supports_credentials' => true
统一过期响应结构，含刷新指引
单纯返回错误不够，应提供可操作反馈。例如：过期时附带 refresh_token 是否可用、下一步建议。
- 捕获
Tymon\JWTAuth\Exceptions\TokenExpiredException - 检查是否启用了 refresh 机制（
refresh_ttl> 0 且请求携带了 refresh token） - 响应示例：
{
"code": 40101,
"message": "登录凭证已过期",
"data": {
"can_refresh": true,
"refresh_hint": "请使用 refresh_token 调用 /api/auth/refresh 接口获取新 access_token"
}
}
禁用 Laravel 默认重定向行为
当 auth:api 或自定义 guard 认证失败时，Laravel 可能尝试重定向到 route('login')，这在 API 场景下会触发 RouteNotFoundException 或 500 错误。
- 确保所有 API 路由使用
middleware('jwt.auth')而非middleware('auth:api') - 删除或注释掉
app/Http/Middleware/Authenticate.php中对 web guard 的重定向逻辑 - 在
config/auth.php中确认'defaults' => ['guard' => 'web']不影响 api 请求 - 若仍报
Route [login] not defined，在routes/web.php或routes/api.php中显式定义一个空路由：Route::get('/login', fn() => abort(404))->name('login');（仅用于满足内部调用，不暴露功能）
