JWT由Header、Payload、Signature三部分组成，以英文句号分隔；Header声明类型与算法，Payload携带用户声明（如uid、exp、iat），Signature通过密钥签名防篡改，确保令牌自包含、可验证、无状态。
直接用 firebase/php-jwt，别碰 ThinkPHP 自带的“JWT”类或手写签名逻辑——那些不是标准实现，也不维护，JWT::encode() 和 JWT::decode() 必须配对使用同一密钥、同一算法、同一时间容错配置，否则 90% 的失败都卡在这三处。
怎么安全生成 token（JWT::encode()）
生成 token 不是拼数组再 base64 编码，核心是签名不可伪造、时间字段语义明确、密钥不裸露。
-
exp和iat必须是int类型秒级时间戳，用time() + 3600，别用date('U')或DateTime::getTimestamp()（可能含微秒） - 密钥必须从配置读取：
config('jwt.secret')，禁止硬编码字符串或md5('xxx')——后者强度不够且易被穷举 - payload 里只放必要字段：
uid、exp、iat、可选scope；绝对不要塞password_hash、phone、email——JWT 是可解码的，不是加密容器 - 别省略
iss（签发方）和nbf（生效时间），哪怕值固定，JWT::decode()默认不校验它们，但业务需要时能防重放或延后生效
怎么正确解析 token（JWT::decode()）
解析失败八成不是 token 损坏，而是 header 提取错误、密钥类型不匹配、或校验开关没开。
- 先安全提取 Bearer token：
preg_match('/^Bearer\s+(?<token>[^\s]+)$/i', $authHeader, $matches)</token>，别用explode(' ', $authHeader)[1]——空格变制表符或缺失 token 就崩 - 必须显式传入算法数组：
JWT::decode($token, new Key($key, 'HS256'), ['HS256'])，漏掉第三个参数会导致算法被绕过 - 务必设
JWT::$leeway = 60，否则服务器与客户端时间差超 1 秒就报ExpiredException（尤其手机端 NTP 同步不准） -
JWT::decode()返回对象，不是数组：$decoded->uid才对，$decoded['uid']会报错 - Apache 环境下
$_SERVER['HTTP_AUTHORIZATION']常为空，要 fallback 到$_SERVER['REDIRECT_HTTP_AUTHORIZATION']
中间件里解析失败的异常怎么分情况处理
同一个 DomainException，原因完全不同，不能统一 return 401。
立即学习“PHP免费学习笔记（深入）”；
-
SignatureInvalidException→ 密钥不一致：检查config/jwt.php中的secret是否和生成时完全相同（注意前后空格、换行） -
ExpiredException→ 不要直接拒绝，先查 Redis 黑名单或数据库确认用户是否被禁用（jti字段需提前存） -
DomainException: Invalid token format→ Authorization 头格式不对，前置加str_starts_with($authHeader, 'Bearer ')校验 - 静默无报错但
$request->getAttribute('uid')为空 → 中间件漏了return $next($request)，ThinkPHP 要求显式返回响应
怎么让 JWT 和原有 RBAC 权限系统共存
不能删掉 think\Auth，JWT 只负责身份识别，权限判断还得走原逻辑。
- 新建
app\common\service\JwtAuth类，实现check($rule, $uid = null)方法，内部调用think\Auth::check($rule, $uid ?? $this->extractUidFromToken()) - 在鉴权中间件里，把解析出的
uid写进请求：$request->withAttribute('uid', $decoded->uid)，后续所有控制器通过$request->getAttribute('uid')获取，彻底脱离 session - 模型事件、命令行任务中禁用 JWT 解析逻辑——没有 HTTP 头，
Authorization不存在，会直接抛未捕获异常
最易被忽略的是时间容错和密钥加载方式：leeway 不设，token 在边缘时间点必然失效；密钥若从环境变量读，记得 trim() 去首尾空白——OpenSSL 对空格敏感，一个看不见的换行就能让整个鉴权链路静默中断。
