Laravel Sanctum 认证失败解决方法

本文详解 Laravel Sanctum 在子域名生产环境中登录成功却提示“Unauthenticated”的根本原因，聚焦于 CSRF Cookie 未正确设置的问题，涵盖 CORS 配置、Session 域名设置及 Sanctum stateful 域名白名单的精准配置要点。

本文详解 Laravel Sanctum 在子域名生产环境中登录成功却提示“Unauthenticated”的根本原因，聚焦于 CSRF Cookie 未正确设置的问题，涵盖 CORS 配置、Session 域名设置及 Sanctum stateful 域名白名单的精准配置要点。

在使用 Laravel Sanctum + Vue 构建前后端分离应用时，本地开发环境一切正常，但部署至生产子域名（如 sub.my-domain.com）后出现「登录成功却无法通过 auth:sanctum 中间件校验」的问题——典型表现为 /sanctum/csrf-cookie 返回 204 但浏览器未收到 XSRF-TOKEN Cookie，后续请求始终被判定为未认证。该问题并非逻辑错误，而是跨域会话与安全策略配置失配所致。

关键配置三要素

要使 Sanctum 的无状态会话机制在子域名下可靠工作，需同时满足以下三项配置要求：

✅ 1. Session 配置：确保 Cookie 可被子域名共享

在 config/session.php 中确认以下选项（尤其注意 secure 和 same_site）：

'secure' => env('SESSION_SECURE_COOKIE', false), // 生产未启用 HTTPS 时必须为 false
'http_only' => true,
'same_site' => 'lax', // 推荐值；若需跨站 POST 提交可设为 'none'（但需同时启用 secure）
'domain' => env('SESSION_DOMAIN', '.my-domain.com'), // 必须带前导点号，表示通配所有子域名

⚠️ 注意：.my-domain.com 中的 . 是必需的，它声明 Cookie 对 my-domain.com 及其所有子域名（如 sub.my-domain.com、api.my-domain.com）均有效；若写成 sub.my-domain.com 则仅对该子域名生效，导致 CSRF Token 无法在后续请求中携带。

✅ 2. Sanctum 白名单：精确声明 stateful 域名

在 config/sanctum.php 中，stateful 数组必须显式包含前端访问的完整子域名（不含协议和端口）：

'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1,.my-domain.com,sub.my-domain.com'
)),

并在 .env 中严格定义（不加 http://，不加端口，子域名需完整写出）：

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

? 验证技巧：dd(Sanctum::stateful()); 可在路由中调试输出当前生效的 stateful 域名列表，确保 sub.my-domain.com 出现在其中。

✅ 3. Axios 请求必须携带凭据

Vue 前端发起请求时，所有涉及 Sanctum 的请求（包括 /sanctum/csrf-cookie 和 /api/login）都必须启用 withCredentials: true：

// 正确：两次请求均开启凭据
axios.get('/sanctum/csrf-cookie', { withCredentials: true })
  .then(() => {
    axios.post('/api/login', { email, password }, { withCredentials: true }) // ← 此处同样需要！
      .then(res => {
        // 登录成功，后续请求自动携带 Cookie
        router.push('/sales-dashboard');
      });
  });

若遗漏第二个请求的 withCredentials: true，虽能完成登录（因 API 层可能绕过 session 校验），但后续受 auth:sanctum 保护的接口将因缺失会话 Cookie 而拒绝访问。

补充检查项

• CORS 中间件：确保 app/Http/Middleware/Cors.php 或 fruitcake/laravel-cors 配置允许凭据传递：

  'supports_credentials' => true,
  'allowed_origins' => ['https://sub.my-domain.com'], // 显式列出前端域名

• Docker 网络与反向代理：若使用 Nginx/Apache 作为反向代理，需透传 Cookie 和 X-Requested-With 头，并禁用 proxy_buffering（避免响应头截断）。
• 浏览器开发者工具验证：在 Application → Cookies 标签下，确认 XSRF-TOKEN 和 laravel_session 是否在 /sanctum/csrf-cookie 后成功写入，且 Domain 显示为 .my-domain.com。

总结

Laravel Sanctum 的子域名认证失效，本质是「会话 Cookie 的作用域」与「Sanctum 的可信域名白名单」未对齐。只需三步即可修复：
① SESSION_DOMAIN=.my-domain.com（带前导点）；
② SANCTUM_STATEFUL_DOMAINS=sub.my-domain.com（精确子域名）；
③ 所有 Axios 请求添加 { withCredentials: true }。
配置完成后，/sanctum/csrf-cookie 将正确设置 XSRF-TOKEN，后续请求即可被 Sanctum 中间件成功识别用户会话。