必须集成Firebase JWT库实现Token签发与验证，含Composer安装配置、JwtService封装、全局中间件拦截、Web服务器头透传及多端差异化鉴权五步。
如果您在ThinkPHP项目中需要实现标准化、高安全性的用户身份认证，则必须集成Firebase JWT库完成Token签发与验证。以下是具体实施的多种方法：
一、通过Composer安装并配置基础依赖
此方法为最直接、官方推荐的集成路径，确保使用稳定兼容版本，避免因PHP或TP版本不匹配引发运行时异常。必须从命令行执行安装，并手动确认版本约束。
1、在项目根目录执行命令：composer require firebase/php-jwt:^6.10
2、确认当前PHP版本不低于7.4且低于8.1（^6.10不兼容PHP 8.1+）
立即学习“PHP免费学习笔记（深入）”；
3、在config/目录下新建jwt.php配置文件，内容仅包含密钥与算法声明：
4、禁止将密钥硬编码于控制器或服务类中；必须通过环境变量或配置文件加载
二、封装独立JwtService服务类
此方法将JWT核心逻辑收口至单一服务类，规避配置驱动扩展带来的缓存污染、字段遗漏与时间偏移校验失败等常见问题，提升可测试性与可控性。
1、在app/service/下创建JwtService.php，定义命名空间app\service
2、构造函数中从$_ENV['JWT_SECRET']读取密钥，若未设置则抛出异常而非回退默认值
3、encode()方法强制注入iat、exp、jti三字段，其中exp设为time() + 3600
4、decode()方法使用new Key($this->secret, 'HS256')传参，禁用空数组或字符串直传
5、所有payload中不得包含password、mobile、id_card等明文敏感字段
三、构建中间件实现全局Token拦截
此方法在请求入口层统一提取、解析并绑定用户上下文，确保业务控制器无需感知认证细节，同时兼容跨域预检请求，防止OPTIONS被错误拦截。
1、创建中间件类app/middleware/JwtAuthMiddleware.php
2、在handle()方法起始处判断$request->method() === 'OPTIONS'，若是则直接返回$next($request)
3、调用$request->header('authorization')获取原始头（注意小写），使用trim()清除空格后匹配Bearer\s+(.+)
4、对提取出的token执行JwtService::decode()，成功后调用$request->withAttribute('uid', $decoded->uid)
5、中间件末尾必须显式返回$next($request)，否则请求链中断且无报错
四、适配Nginx/Apache透传Authorization头
此方法解决90%的“中间件取不到token”问题，根源在于Web服务器默认过滤或重写Authorization头，导致ThinkPHP无法读取原始值。
1、若使用Nginx，在反向代理配置块中添加：proxy_set_header Authorization $http_authorization;
2、同时追加：fastcgi_pass_request_headers on;
3、若使用Apache，启用mod_headers模块，并在虚拟主机配置中加入：RequestHeader set Authorization "%{HTTP:Authorization}e"
4、重启对应Web服务进程，验证$_SERVER['HTTP_AUTHORIZATION']是否非空
5、禁止在PHP代码中尝试读取$_SERVER['Authorization']——该键名在多数环境下不存在
五、实现多端设备区分与差异化鉴权
此方法通过扩展JWT payload字段，在中间件中识别Web/App/小程序等终端类型，支撑不同登录态策略与权限拦截规则。
1、签发token时在payload中注入device字段，值为web、app或miniapp
2、可选扩展app_id（如com.example.myapp）或origin（用于Web端白名单校验）
3、中间件解析成功后，检查$decoded->device值，对miniapp额外校验$decoded->aud === 'miniapp'
4、对app端验证isset($decoded->app_id)且非空，否则拒绝访问
5、未携带device字段的token一律视为非法，不可降级处理
