直接用composer require firebase/php-jwt可安装，但跨域验证失败主因是Web服务器未透传Authorization头、中间件未放行OPTIONS请求、或encode/decode算法与密钥类型不匹配；PHP 8.1+需改用lcobucci/jwt等替代方案。
直接用 composer require firebase/php-jwt 就能装上，但跨域身份验证失败往往不是库没装好，而是头没透传、中间件没放行 OPTIONS、或密钥/算法不匹配——这些才是真卡点。
安装时必须确认 PHP 版本与 JWT 库兼容性
firebase/php-jwt ^6.10 是当前最稳的版本，但它明确不支持 PHP 8.1+。如果你的环境是 PHP 8.1 或更高（比如 8.2、8.3），composer require firebase/php-jwt 会装上但运行时报错：Firebase\JWT\Key 类找不到，或签名验证静默失败。
- 执行
php -v先确认版本；若 ≥8.1，降级 PHP 或改用其他 JWT 实现（如lcobucci/jwtv4+） - PHP 7.4–8.0：指定安装
composer require firebase/php-jwt:^6.10，避免自动升级到不兼容的 v7+ - 装完立刻验证：
class_exists('Firebase\JWT\JWT')返回true才算真正可用
跨域请求下 Authorization 头被丢弃的典型原因
前端发请求带了 Authorization: Bearer xxx，但后端 $request->header('authorization') 拿不到——大概率是 Web 服务器（Nginx/Apache）没透传这个头，或者预检请求（OPTIONS）被中间件拦截了。
- Nginx 配置里必须显式放行：
add_header Access-Control-Allow-Headers "Authorization, Content-Type"; - Apache 要启用
mod_headers，并在.htaccess或虚拟主机中加：Header always set Access-Control-Allow-Headers "Authorization, Content-Type" - 中间件开头必须判断
$request->method() === 'OPTIONS'并直接return $next($request)，否则预检失败，浏览器根本不会发后续带 token 的请求
decode() 报错 “Invalid signature” 的三个高频原因
不是密钥写错了这么简单，常见于 payload 时间字段、Key 构造方式、或算法声明不一致。
立即学习“PHP免费学习笔记（深入）”；
- payload 中漏了
iat或exp字段：JWT::decode()默认校验时间，没这两个字段直接抛异常 - 用了字符串当 key：
JWT::decode($token, $secret, ['HS256'])已过时且不安全；必须用new Key($secret, 'HS256') - encode 和 decode 用的算法不一致：比如 encode 用
HS256，decode 却传['RS256']，报错信息一样是 “Invalid signature”
多端 Token 兼容性容易忽略的细节
Web 端和 App 端共用一套 JWT 验证逻辑，但它们对 exp、jti、aud 的要求可能不同——硬编码在服务类里会导致某端失效。
- 不要在
JwtService::encode()里写死'exp' => time() + 3600；应从配置读：config('jwt.expires_in.web')和config('jwt.expires_in.app') -
aud字段建议按来源区分：Web 端填'web'，App 填'mobile'，decode 时用JWT::setAudience()校验 - 移动端常需刷新机制，但
firebase/php-jwt不提供 refresh token 内置逻辑，得自己在 payload 里加refresh_exp字段并单独校验
真正麻烦的从来不是生成 token，而是让每个环节——从 Nginx 头透传、中间件放行 OPTIONS、Key 实例化方式、到多端 exp 差异——全部对齐。少一个，前端就 401，后端还查不出错在哪。
