LaravelSanctum認證失敗解決辦法

本文深入剖析了 Laravel Sanctum 在生产子域名环境（如 sub.my-domain.com）中登录成功却频繁返回 “Unauthenticated” 错误的根本原因——并非代码逻辑缺陷，而是 CORS、会话 Cookie 域设置（SESSION_DOMAIN）与 Sanctum 状态域（SANCTUM_STATEFUL_DOMAINS）三者不一致导致的 CSRF 令牌与会话凭据同步失效；文章直击痛点，提供一套经过验证的、可立即落地的三步配置修复方案：精准设置 session.php 的 same_site 和 secure 策略、严格规范 .env 中的 SESSION_DOMAIN（必须以点开头）与 SANCTUM_STATEFUL_DOMAINS（仅写子域名主体）、精简 sanctum.php 配置并依赖环境变量，同时强调前端 Axios 必须全局启用 withCredentials 并按序调用 CSRF 刷新与登录接口，辅以实用的浏览器调试技巧，助你彻底打通子域名下的 Sanctum 认证链。

本文详解 Laravel Sanctum 在子域名生产环境中因 CORS 配置、会话域设置及 Sanctum 状态域（stateful domains）不匹配导致的登录后仍返回 “Unauthenticated” 的典型问题，并提供完整可落地的配置修复方案。

本文详解 Laravel Sanctum 在子域名生产环境中因 CORS 配置、会话域设置及 Sanctum 状态域（stateful domains）不匹配导致的登录后仍返回 “Unauthenticated” 的典型问题，并提供完整可落地的配置修复方案。

在使用 Laravel Sanctum + Vue 构建前后端分离应用时，本地开发一切正常，但部署至生产子域名（如 sub.my-domain.com）后出现「登录成功却无法通过 auth:sanctum 中间件校验」的问题，根本原因通常并非逻辑错误，而是跨域会话与 CSRF 令牌同步失效——具体表现为 /sanctum/csrf-cookie 接口返回 204 但浏览器未保存 XSRF-TOKEN 和 laravel_session Cookie，导致后续请求缺失认证凭据。

✅ 关键配置修复清单

请按顺序核查并修正以下三处核心配置：

1. config/session.php —— 会话安全策略必须匹配部署环境

'secure' => env('SESSION_SECURE_COOKIE', false), // 生产无 HTTPS 时务必设为 false
'same_site' => 'lax', // 强烈建议显式设为 'lax'（而非 null 或 'strict'），确保子域间 Cookie 可发送

⚠️ 注意：若服务器未启用 HTTPS（即 APP_URL 为 http://），secure: true 将阻止浏览器存储任何 Cookie，直接导致认证链断裂。

2. .env —— 精确声明状态域与会话域

SESSION_DRIVER=cookie
SANCTUM_STATEFUL_DOMAINS=sub.my-domain.com
SESSION_DOMAIN=.my-domain.com
SESSION_LIFETIME=120
SESSION_SECURE_COOKIE=false

• SANCTUM_STATEFUL_DOMAINS 仅填写子域名主体（如 sub.my-domain.com），不要加协议、端口或通配符；
• SESSION_DOMAIN 必须以 . 开头（如 .my-domain.com），表示该 Cookie 对 my-domain.com 及其所有子域（sub.my-domain.com, api.my-domain.com）均有效；
• SESSION_SECURE_COOKIE=false 是 HTTP 环境下的强制要求（HTTPS 环境下才设为 true）。

3. config/sanctum.php —— 避免硬编码冗余，依赖环境变量

'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,localhost:3000,127.0.0.1')),

✨ 删除原配置中 sprintf 拼接的冗余逻辑（如自动解析 APP_URL），避免因 URL 格式异常（含 http://）导致域名匹配失败。生产环境只需确保 .env 中 SANCTUM_STATEFUL_DOMAINS 值准确即可。

? Vue 前端请求必须携带凭据

确保 Axios 全局配置启用 withCredentials：

// axios.js 或 main.js 中
axios.defaults.withCredentials = true;

并在登录流程中严格按顺序调用：

// 正确示例：先刷 CSRF，再登录
await axios.get('/sanctum/csrf-cookie', { withCredentials: true });
const res = await axios.post('/api/login', { email, password }, { withCredentials: true });

? withCredentials: true 必须显式传入每个请求（包括 csrf-cookie 和 login），否则浏览器不会发送 Cookie，服务端也无法建立会话。

? 验证与调试技巧

• 使用浏览器开发者工具 → Application → Cookies，确认访问 /sanctum/csrf-cookie 后是否存入 XSRF-TOKEN 和 laravel_session，且 Domain 列显示为 .my-domain.com；
• 检查响应头 Set-Cookie 是否包含 Domain=.my-domain.com; Path=/; Secure; HttpOnly; SameSite=Lax（Secure 仅 HTTPS 环境存在）；
• 运行 php artisan config:clear && php artisan cache:clear 确保配置生效。

完成上述配置后，Sanctum 将正确识别子域名请求为「状态化（stateful）」，自动绑定会话与 CSRF 令牌，auth:sanctum 中间件即可稳定通过认证校验。核心原则是：前端凭据传递、后端 Cookie 域策略、中间件状态域三者必须严格一致。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《LaravelSanctum認證失敗解決辦法》文章吧，也可关注golang学习网公众号了解相关技术文章。