Laravel Sanctum SPA 认证需三步：先 GET /sanctum/csrf-cookie 获取 CSRF cookie，再 POST /login 提交凭证（浏览器自动带 XSRF-TOKEN），最后用返回的 Bearer token 调用受保护 API；关键在于确保 EnsureFrontendRequestsAreStateful 中间件位置正确、CORS 支持凭据且允许具体源、auth:sanctum guard 驱动设为 sanctum，并完成数据库迁移。
你在 Vue 或 React 项目里调用 Laravel 后端 API 总是返回 419 或 401，登录接口反复失败，不是密码错、也不是路由没写对，而是 SPA 认证流程根本没走通——Laravel Sanctum 对 SPA 不是发个 token 就完事，它强制要求先拿 CSRF cookie 再登录，且整个链路依赖跨域凭据、中间件顺序和会话状态三者严丝合缝。
安装与数据库准备
执行 composer 安装 Sanctum 包：composer require laravel/sanctum
发布配置与迁移文件：php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
运行迁移创建 personal_access_tokens 表：php artisan migrate
这一步必须完成，否则 createToken() 调用会直接抛出 QueryException，表不存在无法写入 token 记录。
配置 Auth Guard 和中间件
打开 config/auth.php，确认 'api' guard 使用 sanctum 驱动：
【'driver' => 'sanctum'】 必须显式设置，若仍为 token 或 session，auth:sanctum 中间件将无法识别请求身份。
编辑 app/Http/Kernel.php，在 $middlewareGroups['api'] 数组开头插入 Sanctum 的状态保持中间件：
【\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class】 这行必须在 'throttle:api' 之前，否则跨域凭据被拦截，CSRF 校验永远不触发。
该中间件负责判断请求是否来自可信前端域名，并启用 session + cookie 支持——漏掉它，/login 永远 419。
跨域（CORS）与 Cookie 设置
修改 config/cors.php：
确保 'supports_credentials' => true，否则浏览器拒绝发送 Cookie，XSRF-TOKEN 和 laravel_session 都不会携带。
'allowed_origins' 必须写具体前端地址，例如 ['http://localhost:5173']，【不能填 *】，填星号会导致 supports_credentials 自动失效，Chrome 直接屏蔽 Cookie 传输。
'paths' 至少包含 'sanctum/csrf-cookie' 和 'api/*'，否则预检请求被拒，CSRF cookie 根本设不上。
前端认证三步操作流程
第一步：发起 GET 请求获取 CSRF cookie
使用 fetch 发起：fetch('/sanctum/csrf-cookie', { method: 'GET', credentials: 'include' })
使用 axios 时需全局设置：axios.defaults.withCredentials = true
这一步必须成功响应 204，且响应头含 Set-Cookie: XSRF-TOKEN=xxx；若返回 404，检查路由是否存在或中间件是否注册；若返回 204 但无 cookie，检查 CORS 配置是否生效。
第二步：提交登录凭证
POST /login，body 传 email/password，headers 中【不手动加 X-XSRF-TOKEN】，浏览器会自动从 cookie 提取并注入 XSRF-TOKEN 头——手动加反而触发校验失败。
后端 login 方法中，Auth::attempt($credentials) 成功后，立即生成 token：$token = auth()->user()->createToken('spa')->plainTextToken
第三步：返回 token 并持久化
响应体返回 { "token": "abcd1234..." }，前端存入 localStorage 或 pinia，后续所有请求在 Authorization 头中携带：Bearer abcd1234...
注意：这个 token 是明文，【绝不可存进 cookie】，否则 XSS 可直接窃取；也不应存在 sessionStorage，刷新即丢，影响用户体验。
保护 API 路由
在 routes/api.php 中，用 auth:sanctum 中间件包裹受保护路由：
Route::get('/user', function (Request $request) { return $request->user(); })->middleware('auth:sanctum');
auth:sanctum 会按顺序尝试两种方式：先查 laravel_session + XSRF-TOKEN（SPA 场景），失败再查 Authorization Bearer token（移动端 fallback）——无需拆成两个中间件。
若只想走 token 路径（如禁用 session），可改用 auth:api guard，但需同步调整 config/auth.php 中 api guard 的 driver 为 sanctum，并确保路由未被 EnsureFrontendRequestsAreStateful 干扰。
登出处理
前端发送 DELETE 请求到 /logout，headers 带上 Authorization: Bearer {token}
后端 logout 方法中执行：auth()->user()->currentAccessToken()->delete()
这一步删除的是当前设备 token，不是清空 localStorage ——前端必须在收到 204 响应后，再手动移除本地存储的 token 和用户信息，否则下次请求仍带无效 token 导致 401。
