Laravel 8 如何配置 Sanctum 实现前后端分离 API 认证
Laravel 8 使用 Sanctum 实现 API 认证时，必须执行 php artisan migrate 创建 personal_access_tokens 表，否则会出现 SQLSTATE[42S02]: Base table or view not found 错误。
原因分析
Sanctum 是 Laravel 官方推荐的轻量级 API 认证方案，专为 SPA 设计，基于 token + CSRF 实现无状态认证。很多开发者遇到 401 认证失败，核心原因是混淆了 Sanctum 的两种模式：SPA 模式（带 session）和 Token 模式（无状态 API）。根据 2026 年 4 月 4 日的技术资料，Laravel 9+ 默认在 api 中间件组已预设 sanctum，但 Laravel 8 需要手动在 app/Http/Kernel.php 的 api 中间件组中添加 \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class。若 config/sanctum.php 中的'stateful'配置未匹配实际请求来源域名，API 认证会失败却无明确报错。
解决方案
第一步：安装与基础配置
在 Laravel 8 项目中执行以下命令（来自 2022 年 3 月 28 日 CSDN 博客实测）：
1. composer require laravel/sanctum
2. php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
3. php artisan migrate（生成 personal_access_tokens 表）
在 app/Models/User.php 中引入 HasApiTokens trait：
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable { use HasApiTokens; }
注意：若漏掉 HasApiTokens，调用 createToken() 时会报错"Call to undefined method"。
第二步：配置跨域与 Stateful 域名
前后端分离需配置跨域，安装 fruitcake/laravel-cors 包（2025 年 9 月 6 日资料）：
composer require fruitcake/laravel-cors
在 config/cors.php 中设置 allowed_origins 为 Vue 应用域名，如 ['http://your-vue-app.com']。在.env 中配置 SANCTUM_STATEFUL_DOMAINS=your-vue-app.com（多个用逗号分隔，不要带协议或端口）。根据 2026 年 2 月 23 日教程，若前端跑在 http://test.local:3000 但没加进环境变量，会静默 fallback 到 token 认证，导致 401 错误。
第三步：实现登录接口生成 Token
在 routes/api.php 中定义登录路由（2025 年 11 月 13 日实测代码）：
Route::post('/login', function(Request $request) {
$credentials = $request->only('email', 'password');
if(Auth::attempt($credentials)) {
$user = Auth::user();
$token = $user->createToken('auth_token')->plainTextToken;
return response()->json(['token' => $token], 200);
}
return response()->json(['message' => 'Invalid credentials'], 401);
});
关键：必须取$token->plainTextToken，若直接返回整个模型会报错"Object of class Laravel\Sanctum\NewAccessToken could not be converted to string"（2026 年 2 月 23 日常见错误记录）。
第四步：保护 API 路由
在 routes/api.php 中使用 middleware('auth:sanctum')（2025 年 12 月 16 日官方推荐）：
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', function (Request $request) { return $request->user(); });
});
注意：纯 API 场景应使用'sanctum'中间件，auth:sanctum 专用于 SPA 路由（2026 年 4 月 4 日技术说明）。
第五步：前端携带 Token 请求
前端拿到 token 后存在 localStorage 或 Pinia/Vuex 状态中，后续所有 API 请求在 Authorization 头中携带（2025 年 9 月 6 日 Vue 实战）：
Authorization: Bearer {token}
注意：中间是空格，不是冒号或等号，否则 Postman 测试会返回 401（2026 年 3 月 31 日新手指南）。
注意事项
1. Token 刷新机制：Sanctum 没有自动刷新机制，刷新 token = 创建新 token + 主动删旧 token。代码：$user->currentAccessToken()->delete(); $newToken = $user->createToken();（2026 年 3 月 31 日实测）
2. 登出必须通知后端：前端清除 token 不够，需发送 DELETE 请求到/logout，后端执行 auth()->user()->currentAccessToken()->delete();（2025 年 12 月 16 日）
3. Token 过期时间：由 config/sanctum.php 的'expiration'控制（单位分钟），设为 null 表示永不过期，但生产环境慎用（2026 年 3 月 31 日）
4. 多用户表认证：若有 Student、Teacher 等多表，需为每种用户类型定义独立 Provider 和 Guard，各模型都要引入 HasApiTokens trait（2025 年 10 月 7 日多用户表认证指南）
5. 常见报错 Route [login] not defined：Laravel 自身前端页未登录跳转方法不适用于 API，需自定义未登录的异常处理返回 JSON 格式（2022 年 3 月 28 日 CSDN 博客）
参考来源
来源：CSDN 博客 - Laravel8 Sanctum API 认证 +Vue 问卷 搭建前后端分离 SPA 应用（2022 年 3 月 28 日）
来源：技术教程 - Laravel 怎么实现 API 身份验证 _ Laravel Sanctum 令牌配置方法【教程】（2026 年 2 月 23 日）
来源：新手指南 - LaravelAPI 新手如何做用户认证_LaravelSanctum 认证教程【指南】（2026 年 3 月 31 日）
来源：实践文档 - Composer 如何安装 Laravel Sanctum API 认证_Composer 安装 Laravel Sanctum 实践（2026 年 4 月 4 日）