本文详解 laravel 中 jwt token 有效期配置失效、401 错误频发的根本原因，并提供多用户隔离、双 token 机制、静默续期中间件等生产级实践方案。
本文详解 laravel 中 jwt token 有效期配置失效、401 错误频发的根本原因，并提供多用户隔离、双 token 机制、静默续期中间件等生产级实践方案。
在 Laravel API 项目中，仅修改 respondWithToken() 中的 expires_in 计算逻辑（如 * 1440）无法真正延长 Token 有效时间——因为该字段仅为前端提示值，实际校验由 JWT 库底层 ttl 配置与签名载荷（payload）中的 exp 声明共同决定。若 .env 中 JWT_TTL=60（默认 1 小时），即使前端显示 expires_in=86400（24 小时），服务端仍会在 60 分钟后拒绝该 Token，返回 401 Unauthorized。
✅ 正确配置 Token 有效期（以 1 天为例）
首先确保使用现代维护分支：推荐 php-open-source-saver/jwt-auth（原 tymon/jwt-auth 的活跃继任者）：
composer require php-open-source-saver/jwt-auth
发布配置并生成密钥：
php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider" php artisan jwt:secret
在 .env 中设置 分钟级 TTL（注意单位！）：
JWT_TTL=1440 # 1440 分钟 = 24 小时 JWT_REFRESH_TTL=10080 # 可选：7 天刷新窗口
⚠️ 关键：
JWT_TTL必须为整数分钟，config('jwt.ttl')读取即此值；expires_in应统一用* 60转为秒传递给前端：
protected function respondWithToken(string $token): JsonResponse
{
return response()->json([
'access_token' => $token,
'token_type' => 'bearer',
'expires_in' => config('jwt.ttl') * 60, // ✅ 正确：分钟→秒
]);
}
? 多用户隔离：避免越权与认证失败
当存在 Admin、User、Merchant 等多个模型时，必须区分 Token 来源。否则 auth:admin_api 守卫可能错误验证 user 类型 Token，或因 sub 字段无类型标识导致 Auth::user() 返回 null。
在各模型中注入 type 声明：
// App\Models\Admin.php
use Tymon\JWTAuth\Contracts\JWTSubject;
class Admin extends Authenticatable implements JWTSubject
{
public function getJWTIdentifier()
{
return $this->getKey();
}
public function getJWTCustomClaims(): array
{
return [
'type' => 'admin', // ✅ 强制标识
'model' => self::class,
];
}
}
并在 config/auth.php 中为不同守卫绑定对应 provider 与模型：
'guards' => [
'admin_api' => [
'driver' => 'jwt',
'provider' => 'admins', // 指向 admins provider
],
'api' => [
'driver' => 'jwt',
'provider' => 'users',
],
],
'providers' => [
'admins' => [
'driver' => 'eloquent',
'model' => App\Models\Admin::class,
],
'users' => [
'driver' => 'eloquent',
'model' => App\Models\User::class,
],
],
? 安全续期：双 Token + Redis 状态管理
单纯依赖 auth()->refresh() 存在风险：旧 Token 进入黑名单前仍可被重放。推荐生产环境采用 带状态的 refresh token 机制：
-
登录时生成双 Token：
$accessToken = auth('admin_api')->claims(['jti' => Str::uuid()])->login($admin); $refreshToken = Str::random(64); Redis::setex("refresh:admin:{$admin->id}", 604800, $refreshToken); // 7天 -
自定义
/api/token/refresh接口（严格校验上下文）：public function refresh(Request $request) { $token = $request->bearerToken(); $payload = JWTAuth::getPayload($token); // 解析原始 Token $type = $payload['type'] ?? null; $userId = $payload['sub'] ?? null; $storedRefresh = Redis::get("refresh:{$type}:{$userId}"); if (!$storedRefresh || !hash_equals($storedRefresh, $request->header('X-Refresh-Token'))) { throw new HttpResponseException(response()->json(['error' => 'Invalid refresh token'], 401)); } // 签发新 access_token 并滚动 refresh token $newToken = auth("{$type}_api")->setToken($token)->refresh(); Redis::setex("refresh:{$type}:{$userId}", 604800, Str::random(64)); return $this->respondWithToken($newToken); } -
静默续期中间件（无感体验）：
// app/Http/Middleware/EnsureTokenValid.php public function handle($request, Closure $next) { try { return $next($request); } catch (TokenExpiredException $e) { // 尝试静默刷新 if ($request->header('X-Refresh-Token') && $request->bearerToken()) { $response = $this->refreshToken($request); return $response; } throw $e; } }
? 最后检查清单
- ✅
config/auth.php中guards.api.driver已明确设为'jwt'（非'token'） - ✅
php-open-source-saver/jwt-auth服务提供者已在config/app.php手动注册（Laravel 9+ 需显式添加） - ✅ 登录控制器调用的是
auth('admin_api')->attempt()，且守卫名与配置完全一致 - ✅ 用户模型实现了
JWTSubject，getJWTIdentifier()返回标量（推荐$this->getKey()） - ✅ 前端每次请求携带
Authorization: Bearer <token></token>，且未缓存过期 Token
通过以上配置，Token 将真正按 24 小时生效，续期逻辑安全可控，多用户场景零越权风险——这才是 Laravel JWT 在生产环境的正确打开方式。
