唯一应安装的包是firebase/php-jwt，装错包名、版本不匹配或PHP不兼容占安装失败90%；必须用完整包名composer require firebase/php-jwt:^6.10，v6+要求PHP≥7.4且encode需四参数、decode须用new Key对象。
firebase/php-jwt 是唯一该装的包，其他名字带 jwt 的基本都过时、不维护或强绑定框架。装错包名、版本不匹配、PHP 版本不兼容，这三类问题占安装失败的 90%。
composer require firebase/php-jwt 写错包名就直接报错
别搜 “jwt”“php-jwt”“composer jwt”，也别手敲 tymon/jwt-auth 或 lcobucci/jwt——这些不是通用库，要么已弃用，要么只适配 Laravel/ Symfony。必须用完整包名：composer require firebase/php-jwt:^6.10。
常见错误现象：
-
Could not find package jwt：关键词太模糊，Packagist 不认 -
Installation failed, reverting ./composer.json to its original content.：版本约束冲突，比如项目锁死 PHP 7.2，而firebase/php-jwt:^6.10要求 ≥7.4 - 装完运行却报
Class 'Firebase\JWT\JWT' not found：漏了require 'vendor/autoload.php';，或命名空间大小写写成小写（firebase\jwt\jwt在 Linux 下必炸）
PHP 版本和 autoload 必须对得上
firebase/php-jwt v6+ 要求 PHP ≥7.4；如果你用的是 PHP 8.2，但 composer.json 里写了 "php": "^7.4"，某些旧版会拒绝安装——此时加 @latest 强制拉最新兼容版：composer require firebase/php-jwt:@latest。
autoload 失效的典型表现是 use Firebase\JWT\JWT; 报错。检查以下三点：
- 入口文件第一行是否已引入：
require __DIR__ . '/vendor/autoload.php'; - 是否手动删过
vendor/或composer.lock？如果是，执行composer install（不是require）重装依赖 - 是否在非 Composer 环境下运行？比如 CLI 直接 php test.php 却没加载 autoloader
JWT::encode() 和 JWT::decode() 的参数不能按老教程抄
v6.0+ 彻底改了签名和验签接口，老式三参数写法 JWT::encode($payload, $key, 'HS256') 会抛 ArgumentCountError: Too few arguments。
正确写法分两类：
- HS256（推荐起步）：
JWT::encode($payload, $key, 'HS256', $keyId)，其中$keyId可为null或字符串（如'api-key-1'） - RS256（需密钥对）：
JWT::encode($payload, $privateKey, 'RS256', $keyId)，且$privateKey必须是OpenSSLAsymmetricKey类型（即openssl_pkey_get_private()返回值），传字符串直接抛异常 - 验签必须用
new Key($keyOrPem, $alg)构造对象，不能再只传字符串——v6.9+ 后强制要求，否则静默降级为 HMAC 验证，导致 RS256 token 被 HS256 方式误判
Authorization 请求头透传经常被 Web 服务器拦住
哪怕 token 生成和解码都没问题，$_SERVER['HTTP_AUTHORIZATION'] 仍可能是 MISSING。Apache 默认不透传 Authorization 头，Nginx 也可能过滤。
实操建议：
- 先在入口加一行调试：
var_dump($_SERVER['HTTP_AUTHORIZATION'] ?? 'MISSING'); - Apache：确保
.htaccess或虚拟主机配置含RewriteCond %{HTTP:Authorization} ^(.*$)+RewriteRule .* - [e=HTTP_AUTHORIZATION:%1] - Nginx：在
location块里加proxy_set_header Authorization $http_authorization;（反向代理场景）或fastcgi_param HTTP_AUTHORIZATION $http_authorization;（PHP-FPM 场景） - 验证时前端请求头必须是
Authorization: Bearer eyJhbGciOi...，注意Bearer首字母大写、后面有空格、不能写成Token或JWT
密钥必须是非空字符串，''、null、[] 全部触发 InvalidArgumentException；JWT::ALG_HS256 这类常量必须显式使用，不能传 "HS256" 字符串——这些细节不报语法错，但一跑就崩，而且错误提示极其隐蔽。
