使用Laravel Sanctum访问受保护Web路由时验证失败问题排查

以下是可能导致你遇到的验证失败、重定向登录页问题的几个常见原因：

• 自定义Cookie名称不被默认中间件识别
  Laravel Sanctum的auth:sanctum中间件默认只会从Authorization请求头（格式为Bearer {token}）中提取令牌，不会自动读取你自定义的BEARER-TOKENCookie。如果要从Cookie中取令牌验证，你需要自定义中间件，手动从Cookie中获取令牌并设置到请求头，或者替换默认的Sanctum认证逻辑。

• Web路由混用API认证中间件的适配问题
  auth:sanctum本质是为API无状态认证设计的，而Web路由默认依赖session认证。当Web路由使用auth:sanctum且验证失败时，Laravel的Web中间件栈会把Sanctum返回的401响应自动重定向到登录页。如果你的/my-account是Web页面路由，更适合用auth中间件（session驱动）；如果一定要用Sanctum，需要修改异常处理逻辑，阻止401被重定向，同时确保请求携带CSRF令牌。

• Cookie存储参数配置错误
  注册时存储令牌到Cookie的操作可能存在参数问题：

  • 检查Cookie的domain是否和当前应用域名匹配，跨域名下浏览器不会携带Cookie；
  • 确认path设置正确，比如设为/才能让所有路由请求都携带；
  • 本地开发环境不要开启secure参数（否则只有HTTPS请求才会携带），生产环境按需开启；
  • 示例正确的Cookie设置代码：

    return response()->cookie(
        'BEARER-TOKEN',
        $token->plainTextToken,
        60 * 24 * 30, // 有效期30天
        '/',
        null,
        env('APP_ENV') === 'production', // 生产环境开启secure
        true, // httpOnly，防止XSS
        false, // 不要限制同站，根据需求调整
    );
    

• CSRF保护未正确处理
  对于Web端的Sanctum请求，除了Bearer令牌，还必须携带CSRF令牌。你需要：

  • 在页面中引入@csrf指令（表单提交场景）；
  • 如果是AJAX请求，要从XSRF-TOKENCookie中获取值，设置X-XSRF-TOKEN请求头；
    缺少CSRF验证会直接导致Sanctum拒绝请求，进而触发登录重定向。

• 认证守卫配置异常
  检查config/auth.php中的sanctum守卫配置，确保驱动和用户提供者正确：

  'guards' => [
      'sanctum' => [
          'driver' => 'sanctum',
          'provider' => 'users',
      ],
  ],
  

  若守卫配置错误，auth:sanctum中间件无法正确加载认证逻辑，自然验证失败。

内容的提问来源于stack exchange，提问作者UndercoverCoder