在Laravel中启用Sanctum认证需四步：1. 发布并运行迁移创建personal_access_tokens表；2. 用户模型引入HasApiTokens；3. 配置auth.php中api守卫驱动为sanctum；4. 在Kernel.php的api中间件组顶部注册EnsureFrontendRequestsAreStateful，并清空config/sanctum.php的stateful数组。
在Laravel项目中为API接口启用Sanctum认证，必须先完成环境级初始化：创建数据库表、注入模型能力、配置守卫驱动与中间件链，缺一不可，否则后续所有Token生成和校验都会失败。
安装并发布Sanctum迁移文件
在项目根目录终端执行：composer require laravel/sanctum。
运行命令发布迁移文件：php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"。这一步会把create_personal_access_tokens_table.php复制到database/migrations目录下——如果没看到该文件，说明发布失败，需重试或检查Composer包是否完整安装。
迁移文件发布后立即执行：php artisan migrate。这将创建personal_access_tokens表，【没有这张表，任何createToken()调用都会静默失败】。
用户模型集成HasApiTokens
打开app/Models/User.php，在use语句块中添加：use Laravel\Sanctum\HasApiTokens;。
在class User extends Authenticatable的花括号内插入：use HasApiTokens;。
这一步不是可选项——【缺少HasApiTokens，$user->createToken()方法根本不存在，调用时直接抛出Fatal error】。别忘了保存文件。
配置API守卫驱动为sanctum
编辑config/auth.php，定位到'guards'数组，确认存在以下配置：
'api' => [ 'driver' => 'sanctum', 'provider' => 'users', ],
若不存在，请手动添加。这个配置告诉Laravel：当路由使用auth:sanctum中间件时，应交由Sanctum驱动处理认证逻辑，而不是默认的session或token驱动。
同时检查'defaults' => ['guard' => 'web']保持不变，避免影响后台登录流程。
注册EnsureFrontendRequestsAreStateful中间件
打开app/Http/Kernel.php，找到$middlewareGroups中的'api'数组。
第一步：确认\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class已位于该数组顶部位置。
第二步：确保其下方紧跟着'throttle:api'和\Illuminate\Routing\Middleware\SubstituteBindings::class等基础中间件。
第三步：删除该数组中可能存在的\Illuminate\Session\Middleware\StartSession::class——API路由不应启动Session，否则会干扰Token解析流程。
这一步是API模式下最关键的中间件注册，它让Sanctum能同时识别Cookie（SPA）和Authorization头（移动端/API客户端）两种认证方式。
禁用stateful域名匹配（开发环境必做）
打开config/sanctum.php，找到'stateful'配置项。
方法一：开发阶段最稳妥的做法是清空整个数组，改为'stateful' => []。这样Sanctum将完全跳过Cookie认证路径，强制走Bearer Token校验。
方法二：若前端运行在http://localhost:5173，则需从数组中移除'localhost:5173'，否则Sanctum会尝试读取session cookie并忽略你传的Bearer Token，导致401错误。
注意：此配置修改后无需重启服务，但所有已发出的请求会立即生效——改完立刻测试登录接口。
