必须用 composer require firebase/php-jwt，它是PHP生态中维护最活跃、无框架绑定、文档最清晰的通用JWT库；其他如 jwt、php-jwt、tymon/jwt-auth 要么不存在要么仅限Laravel。
别直接 composer require jwt，这命令必然失败——Composer 根本不认识 jwt 这个包名。
必须用完整包名 firebase/php-jwt
这是当前 PHP 生态中维护最活跃、无框架绑定、文档最清晰的通用 JWT 库。其他名称（如 jwt、php-jwt、tymon/jwt-auth）要么不存在，要么是 Laravel 专用插件，不能直接用于原生 PHP 或 ThinkPHP/Lumen 等非 Laravel 项目。
-
composer require firebase/php-jwt是默认安装最新稳定版（v6+），要求 PHP ≥ 7.4 且启用openssl扩展 - 若项目还在跑 PHP 7.2，得加版本约束：
composer require firebase/php-jwt:^5.2 - 国内源不稳定时，先配镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
use Firebase\JWT\JWT 必须写，否则 Class not found
装完不等于能用。firebase/php-jwt 不提供全局函数，全靠命名空间和自动加载。常见报错 Class "Firebase\JWT\JWT" not found，90% 是因为漏了 use 声明。
- 文件顶部必须有：
use Firebase\JWT\JWT;（v6+）或use Firebase\JWT\JWT;+use Firebase\JWT\Key; - v6+ 的
JWT::encode()第三个参数必须是常量JWT::ALG_HS256，不能传字符串"HS256" - 密钥
$key必须是非空字符串，从.env读取时注意trim()换行符，否则会抛InvalidArgumentException
鉴权失败八成是 Header 或密钥对不上
JWT::decode() 报 SignatureInvalidException，基本不用查解码逻辑——先盯死两件事：
- 请求头格式必须是：
Authorization: Bearer <token></token>（Bearer首字母大写，中间一个空格） - 服务端用的密钥（
$key）必须和签发时**逐字节一致**：包括是否含前后空格、换行、编码方式（比如base64_decode()后再用，和直接用原始字符串，效果完全不同） - 如果用 Nginx / Apache，确认它透传了
Authorization头（Nginx 需加proxy_pass_request_headers on;，Apache 可能需RewriteRule ^(.*)$ %{ENV:REDIRECT_HTTP_AUTHORIZATION} [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]）
别碰 tymon/jwt-auth，除非你锁死 Laravel 8
这个包在 Laravel 9+ 已彻底失效：v1.0.2 不兼容 PHP 8.1+ 类型系统，依赖已被移除的 booting() 钩子，装完就报 Class "Tymon\JWTAuth\Providers\LaravelServiceProvider" not found 或 Command not found。
- Laravel 9+ 官方推荐
laravel/sanctum，不是权宜之计，是设计层面的替代 - 非要用 JWT 刷新机制？那得自己实现黑名单位置、密钥轮换、跨域存储策略——这些细节在生产环境里比“生成 token”难十倍
- Lumen 项目也别硬套
tymon/jwt-auth，它没为 Lumen 做适配，firebase/php-jwt足够轻量且可控
