ThinkPHP 本身不内置 JWT 支持，必须集成 firebase/php-jwt 等第三方库；因 Auth 类依赖服务端状态（如 Session），而 JWT 是无状态的，硬套会导致校验仍查库、刷新与黑名单无法对齐、Auth::check() 无法准确反映 JWT 有效性。
ThinkPHP 本身不内置 JWT 支持，必须手动集成第三方库或自行实现核心逻辑；直接用 tp-jwt 或 firebase/php-jwt 是最稳妥的路径，但要注意密钥管理、token 刷新和黑名单机制这三处最容易出问题。
为什么不能直接用 ThinkPHP 自带的 Auth 类做 JWT？
ThinkPHP 的 Auth 和 Session 组件默认依赖服务端状态（如 session 文件或数据库记录），而 JWT 的本质是「无状态」——所有认证信息都编码在 token 字符串里，服务器不存 session。硬套 Auth 类会导致：
- token 校验时仍去查数据库，失去 JWT 的轻量优势
- 刷新 token、黑名单失效等操作无法与原有 Auth 流程对齐
-
Auth::check()返回 true 仅表示「有登录态」，不等于「JWT 有效」
推荐集成 firebase/php-jwt 的实操步骤
这是目前最稳定、文档最全的 PHP JWT 库，ThinkPHP 6/8 均可直接使用：
- 执行
composer require firebase/php-jwt安装 - 在
app/common/JwtAuth.php中封装基础方法，避免在控制器里重复写签名/解析逻辑 - 密钥必须从配置读取，禁止硬编码：
config('jwt.secret')，且建议用openssl_random_pseudo_bytes(32)生成 - 生成 token 时，
exp（过期时间）务必用time() + 3600这类相对时间，别用固定时间戳
示例生成代码片段：
立即学习“PHP免费学习笔记（深入）”；
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
$payload = [
'uid' => $user['id'],
'username' => $user['username'],
'iat' => time(),
'exp' => time() + 3600,
'jti' => uniqid(),
];
$token = JWT::encode($payload, config('jwt.secret'), 'HS256');
如何在中间件中校验 JWT 并绑定用户信息？
ThinkPHP 的中间件是拦截请求、注入用户上下文的最佳位置，但注意两点：
- 不要在中间件里调用
$this->error()直接返回 JSON，应统一抛出ValidateException或自定义异常，由全局异常处理接管 - 校验失败时，
Authorization头缺失或格式错误（如不是Bearer xxx）要单独判断，否则JWT::decode()会直接报致命错误 - 解码成功后，必须验证
exp和nbf（生效时间），firebase/php-jwtv6+ 默认已启用，但低版本需手动传new Key(config('jwt.secret'), 'HS256')
关键校验逻辑节选：
$authHeader = $request->header('authorization');
if (!$authHeader || strpos($authHeader, 'Bearer ') !== 0) {
throw new ValidateException('Token missing or malformed');
}
$token = trim(substr($authHeader, 7));
try {
$decoded = JWT::decode($token, new Key(config('jwt.secret'), 'HS256'));
$request->userInfo = (array) $decoded; // 注入到 request 对象供后续使用
} catch (\Exception $e) {
throw new ValidateException('Invalid token: ' . $e->getMessage());
}
刷新 token 和黑名单怎么落地？
JWT 本身不支持主动失效，所以「退出登录」或「强制下线」必须靠外部机制：
- 刷新 token 不建议用单一 refresh token，而是每次访问都生成新 access token（带新
jti），旧 token 在窗口期内仍有效，降低并发冲突 - 黑名单可用 Redis 实现：
setex jwt:blacklist:{$jti} 3600 true，校验时先查 Redis 是否存在该jti - 别把黑名单 key 设为永不过期，否则内存泄漏；过期时间应 ≥ token 最长有效期
- 前端必须在每次收到新 token 后覆盖本地存储，否则下次请求仍发旧 token，导致「登出后还能继续用」
真正容易被忽略的是：token 解析后得到的用户数据，不能直接当权限依据。比如 role 字段应在数据库查最新值，而不是信任 payload 里的旧快照。
