一、背景与原理概览
JSON Web Token 是一种紧凑、自包含的令牌格式，常用于无状态的 API 鉴权。它由三段结构组成：头部（Header）、载荷（Payload）、签名（Signature），通过将头部和载荷进行 Base64 编码后按指定算法生成签名。
在 无状态认证 场景下，服务端无需存储会话信息，只凭借令牌中的声明来鉴权。对于 PHP 应用，JWT 提供了跨域、跨进程的认证能力，尤其适合微服务架构和移动端接口。
完整的实现流程 通常包括令牌的签发、传输、验证、以及过期与刷新策略，这也是本指南要覆盖的“从原理到代码实战”的核心部分。
JWT 的基本原理
Header 指定算法和令牌类型，Payload 保存对鉴权有用的用户信息与权限字段，Signature 确保令牌在传输过程中未被篡改。
通过在头部指定 算法（如 HS256、RS256），服务端可对令牌进行签名校验，从而实现 无状态鉴权。这是实现快捷、可扩展的 API 认证方案的核心。
在 PHP 的应用优势
在 PHP 生态中，JWT 可以与框架无缝集成，如 Laravel、Slim、以及自定义路由中间件。轻量、无服务端会话存储的特性降低了服务端状态管理的复杂性。
通过 Bearer 令牌 的方式将 JWT 放在 HTTP 请求头部，能实现对 API 的快速鉴权，提升并发性能与伸缩性。
需要注意的是 密钥安全、算法选择与 令牌轮换策略等安全要点，是确保 JWT 安全性的关键。
二、核心概念与工作流程
令牌结构与声明
JWT 的载荷中包含若干标准声明（如 iss、sub、exp、aud、iat）以及自定义数据。通过在头部指定 算法（如 HS256、RS256），服务端可对令牌进行签名校验。
Header 指定算法和令牌类型，Payload 保存对鉴权有用的用户信息与权限字段，Signature 确保令牌在传输过程中未被篡改。
常见做法是在前后端通信时，将令牌放入 Authorization: Bearer 头部，服务端在每次请求时进行 解码与验证。
签名与密钥管理
签名阶段使用对称密钥（HS256）或非对称密钥对（RS256）。HS256 需要同一密钥在签发与验证两端保持一致，RS256 则可使用公私钥对，提升分离与安全性。
密钥管理是安全的核心。要避免硬编码在代码中，推荐使用环境变量或密钥管理服务，并实行密钥轮换与过期策略，以降低被妥协的风险。
三、在 PHP 中实现 JWT 的准备工作
环境准备与依赖
准备一个 PHP 项目并通过 Composer 安装官方或社区维护的 JWT 库，例如 firebase/php-jwt，以获得稳定的编解码能力。
在开发阶段，建议开启严格错误处理和日志，以追踪 签发与验证流程 的异常情况，并正确处理 过期 token 与 无效签名 的场景。
选择库与安全考虑
常用选择包括 firebase/php-jwt、以及其他实现。尽量选用活跃维护的版本，并遵循库的官方文档进行 安全签名与解码。
正确处理时效性：设置合理的 exp 与 nbf、iat，避免绕过和重放攻击。
四、具体实现：从原理到代码实战
生成 JWT（签发令牌）
以下示例展示如何在 PHP 中使用 firebase/php-jwt 签发一个包含用户 ID 的令牌，把 exp 设置为 1 小时后过期。
通过将令牌放在响应体中返回给前端，并在后续请求中通过 Authorization: Bearer 头部携带。
'https://my-api.example.com','sub' => 'user-12345','aud' => 'https://my-app.example.com','iat' => time(),'exp' => time() + 3600, // 1 hour
];$secretKey = $_ENV['JWT_SECRET'] ?? 'default_secret';
$jwt = JWT::encode($payload, $secretKey, 'HS256');
echo json_encode(['token' => $jwt]);
?> 验证 JWT（解析与鉴权）
接收到前端传来的 Bearer 令牌后，后端应使用相同密钥对令牌进行验证，确保签名有效且未过期。
验证通过后，可以从解码结果中提取 sub 等字段，以完成授权决策。
sub;// 进行授权判断// ...echo 'OK';
} catch (Exception $e) {http_response_code(401);echo 'Invalid token';
}
?> 五、实战案例：接口保护与鉴权中间件
中间件设计思路
在现代 PHP 应用中，将鉴权逻辑封装为中间件，可以在路由进入前统一校验令牌。解耦合、可复用性高 是核心目标。
中间件通常检查 Authorization 头部，在令牌无效时返回 401；鉴权成功后，将解码的主体信息注入请求上下文，供后续处理使用。
示例：用户登录获取令牌与后续接口鉴权
以下示例展示一个简单的局部路由鉴权流程，包括登录返回令牌的逻辑与受保护接口的访问控制。
通过 中间件调用，未携带有效令牌的请求将被拦截，避免访问受限资源。
'https://my-api.example.com','sub' => $userId,'iat' => time(),'exp' => time() + 3600
];
$secretKey = $_ENV['JWT_SECRET'] ?? 'default_secret';
$token = JWT::encode($payload, $secretKey, 'HS256');// 返回给前端
echo json_encode(['token' => $token]);
?> sub;echo 'Access granted';
} catch (Exception $e) {http_response_code(401);echo 'Invalid token';
}
?> 六、常见坑与安全要点
密钥管理与轮换
确保 密钥不可硬编码，应使用环境变量、配置管理或密钥管理服务，定期轮换并记录历史密钥以支持令牌的平滑验证。
在 RS256 场景中，私钥签名、公钥验证的流程要确保公钥分发的安全性，建议使用轮询的密钥版本（kid）机制。
令牌存储与跨域
前端存储令牌时需注意 XSS/CSRF 风险，推荐优先在 HTTP-only 的 Cookie 或在客户端使用 本地存储与安全策略结合，并在跨域场景下配合 CORS 头部。
服务端应对每次请求都进行 签名校验，避免将敏感信息直接放入载荷中，不要信任客户端，以防止令牌伪造或被窃取后滥用。
