本文详解 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 域策略、中间件状态域三者必须严格一致。
