Laravel怎么处理请求头认证_Laravel Token鉴权实现方法【方法】

在 Lara vel 的 API 开发中，Token 鉴权几乎是绕不开的一环，但不少人在配置时容易踩坑——最典型的就是 guard 选错了。先说一个核心结论：绝大多数情况，API Token 鉴权必须用 Auth::guard('api')，而不是 web guard。这不是什么“API 就该用 api”的教条，而是底层机制决定的——web guard 默认依赖 session，而无状态请求头认证（比如 Authorization: Bearer xxx）根本不会带 session cookie，web guard 会直接跳过 token 解析，导致静默失败，连错误日志都没有。

Token 认证该用 Auth::guard('api') 还是 Auth::guard('web')

绝大多数 Lara vel API Token 鉴权必须用 api guard，不是因为“API 就该用 api”，而是 web guard 默认依赖 session，而无状态请求头认证（比如 Authorization: Bearer xxx）根本不会带 session cookie，web guard 会直接跳过 token 解析，静默失败。

检查 config/auth.php 中 guards.api.driver 是否为 token（Lara vel 8 及以前）或 sanctum/passport（Lara vel 9+）。若你手动写了中间件去读 Authorization 头但没配对 guard，Auth::check() 永远返回 false。

• api guard 默认不启用 session，只从请求头或查询参数提取 token
• web guard 强依赖 StartSession 中间件，且默认忽略 Authorization 头
• 哪怕你用 Auth::loginUsingId() 强行登录，后续请求仍需对应 guard 才能保持认证上下文

Bearer Token 解析失败的三个常见原因

最典型的错误现象是：Postman 发了 Authorization: Bearer abc123，但 Auth::user() 为空，且无任何报错。这不是代码写错了，而是底层解析链断在某个环节。

• 请求头字段名写成 authorization 小写 —— Lara vel 的 Request::bearerToken() 内部调用 getHeader('Authorization')，部分服务器（如 Nginx + FastCGI）会把 header 全转小写，需在配置中加 underscores_in_headers on; 或改用 request()->header('authorization') 手动取值
• Token 存储在数据库字段类型太短 —— api_tokens 表的 token 字段若用 VARCHAR(60)，而 Sanctum 生成的是 64 字符 base64 字符串，后 4 位会被截断，导致哈希比对失败
• 用了 Sanctum::authenticate() 却没传入有效 request 实例 —— 它内部依赖 $request->bearerToken()，如果 request 是 mock 的或未绑定到当前上下文，直接返回 null

Sanctum 中间件 auth:sanctum 不生效？先确认路由组是否漏了 api 前缀

Lara vel 的 api 中间件组默认启用 throttle:api 和 bindings，但它真正关键的作用是：让路由走 App\Http\Kernel.php 中定义的 api 中间件栈，而这个栈里才包含 EnsureFrontendRequestsAreStateful::class（用于处理跨域 Cookie）和 AuthenticateSession::class（仅 web）——但更重要的是，auth:sanctum 中间件只有在 api 路由组下才会自动启用 token 解析逻辑。

• 写在 routes/web.php 里的路由，即使加了 auth:sanctum，也不会触发 token 校验，因为没进 api 中间件栈
• routes/api.php 默认已套了 api 中间件组，但如果你手动删了 ->middleware('api')，auth:sanctum 就形同虚设
• 自定义中间件顺序错误：比如把 auth:sanctum 放在 throttle 后面，而 throttle 触发时用户还没认证，会误判为未登录用户限流

Token 过期时间不受 expires_at 控制？那是你没启用 Sanctum::usePersonalAccessTokens()

Sanctum 的 PersonalAccessToken 模型默认不校验 expires_at 字段，哪怕你在创建时设置了它，中间件照样放行。这不是 bug，是设计选择 —— Sanctum 默认认为 token 有效期靠「主动撤销」而非时间戳控制。

若你确实需要服务端强制过期（比如合规要求），必须显式启用：

use Lara vel\Sanctum\Sanctum;
Sanctum::usePersonalAccessTokens(function ($token) {
    return $token->expires_at ? $token->expires_at->isFuture() : true;
});

这段代码要放在 AppServiceProvider::boot() 里，且注意：它只影响 PersonalAccessToken，不影响 Sanctum::authenticate() 手动验证的场景。

另外，expires_at 是 datetime 类型字段，别存字符串或时间戳整数，否则 Carbon 解析失败，判断永远为 false。