将 laravel 的 token 守卫迁移到 sanctum,核心在于修改 config/auth.php 中的 guards 配置,将对应 guard 的 driver 从 token 改为 sanctum。这一改动会自动接管基于 bearer token 的身份验证逻辑,不再依赖旧的 api_token 字段或手动哈希比对,而是通过 sanctum 管理的 personal_access_tokens 表进行验证。

如何修改 auth.php 以启用 Sanctum 驱动
在 config/auth.php 文件中,找到 guards 数组下的 api 键(或其他自定义 API Guard)。将其 driver 属性从 token 更改为 sanctum,并移除 provider 字段,因为 Sanctum 驱动不需要关联 Eloquent 用户提供者来查找令牌,它直接处理请求头中的 Token。
return [
'guards' => [
'web' => [
'driver' => 'session',
'provider' => 'users',
],
'api' => [
'driver' => 'sanctum', // 从 token 改为 sanctum
// 'provider' => 'users', // 删除此行
],
],
];
修改后,Laravel 的认证中间件 AuthenticateSession 和 EnsureEmailIsVerified 等仍可按需保留,但底层的令牌解析逻辑已切换至 Sanctum 的 TokenGuard。此时,客户端发送的 HTTP 请求需在 Header 中包含 Authorization: Bearer ,Sanctum 会自动提取并验证该令牌的有效性、过期时间及作用域。

Sanctum 中令牌的存储与哈希机制
Sanctum 不存储明文的 Token,而是使用 PHP 的 hash_equals() 函数配合 bcrypt 或 Argon2 算法对 Token 进行哈希处理后存入数据库。当用户创建 Personal Access Token 时,Laravel 会生成一个随机字符串作为 plain_text_token,仅在此刻返回给前端;随后,系统计算其哈希值并存入 personal_access_tokens 表的 token 字段。每次请求到来时,Sanctum 会对请求头中的 Token 进行同样的哈希运算,并与数据库中的哈希值进行恒定时间比较,以防止时序攻击。
// 伪代码展示 Sanctum 内部逻辑
$plainToken = Str::random(40);
$hashedToken = hash('sha256', $plainToken); // 实际可能更复杂
DB::table('personal_access_tokens')->insert([
'token' => $hashedToken,
'name' => 'my-token',
// ...
]);
// 返回给前端的是 $plainToken
这种设计确保了即使数据库泄露,攻击者也无法直接还原出可用的 Token。同时,由于哈希过程是确定性的,Sanctum 可以在无状态的情况下快速验证令牌,无需查询用户表即可确认令牌本身的合法性,再通过 can() 方法检查作用域权限。旧版 token 驱动通常直接比对 api_token 字段的明文或简单哈希,安全性较低且缺乏作用域支持,迁移至 Sanctum 可显著提升 API 安全等级。

迁移后如何处理旧用户的 api_token 字段
迁移完成后,原有的 api_token 字段将不再被认证系统识别。若需兼容旧客户端,建议在过渡期内提供 API 端点,允许旧用户通过密码重新生成新的 Sanctum Token。对于新注册用户,直接使用 Sanctum 的 createToken() 方法生成令牌,并确保前端正确存储和发送 Bearer Token。旧数据中的 api_token 可标记为废弃,或在用户下次登录时自动替换为新令牌,避免混合使用两种认证机制导致的安全隐患。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!











