Sanctum 是 Laravel 9+ 中适用于 SPA 和移动 App 的轻量级 API 认证方案，基于数据库 token 与 Cookie 自动管理实现「登录即认证」，比 Passport 更简单安全；需正确配置 stateful 域名、CSRF 流程、跨域策略及中间件使用。
Sanctum 适合单页应用（SPA）和移动 App 的轻量级 API 认证，它不依赖 OAuth2 复杂流程，而是靠数据库 token + Cookie 自动管理实现「登录即认证」。如果你用的是 Laravel 9+ 且项目不需要多平台统一授权中心，直接上 Sanctum 比 Passport 更省心、更安全、更少 bug。
安装 Sanctum 并发布配置
执行命令安装包并发布配置文件和迁移：
composer require laravel/sanctum php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
这会生成 config/sanctum.php 和数据库迁移文件。迁移前确认你的 users 表有 id 主键且类型为整型（UUID 用户需额外处理）。
- 迁移前务必运行
php artisan migrate，否则调用createToken()会报SQLSTATE[42S02]: Base table or view not found -
sanctum.php中的stateful配置决定哪些域名走 Session + Cookie 认证（如['localhost', '127.0.0.1']），开发环境必须包含前端地址，否则跨域请求无法携带 session - 生产环境记得把
SESSION_DOMAIN设为根域名（如.example.com），否则子域名间 Cookie 不共享
在 API 路由中启用 Sanctum 中间件
Sanctum 提供两个核心中间件：auth:sanctum（校验登录态）和 throttle:api（限流）。它们必须配合 api 路由组使用，但注意：Laravel 默认 api 组不启用 session，所以不能直接用 auth:sanctum —— 必须显式加 middleware('auth:sanctum') 到具体路由或组里。
正确写法示例（routes/api.php）：
use Illuminate\Http\Request;
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', function (Request $request) {
return $request->user();
});
});
- 不要在
api路由中混用web中间件（如web、encrypt_cookies），会导致 CSRF token 错误或 session 初始化失败 - 移动端调用时，token 必须放在
Authorization: Bearer {token}请求头；SPA 浏览器调用则靠 Cookie 自动携带，无需手动传 token - 如果返回
401 Unauthenticated但用户已登录，大概率是前端没发X-XSRF-TOKEN或后端没配好stateful域名
生成与校验 Token 的典型用法
Sanctum 的 token 是模型关联的，每个 token 对应一个 PersonalAccessToken 实例，保存在数据库中。用户登录后，调用 createToken() 创建 token，并把 token 字符串（$token->plainTextToken）返回给前端存储。
示例登录逻辑（AuthController@login）：
if (Auth::attempt($credentials)) {
$user = Auth::user();
$token = $user->createToken('api-token');
return response()->json([
'user' => $user,
'token' => $token->plainTextToken,
]);
}
-
createToken()第二个参数可传权限数组（如['read', 'write:posts']），后续可用$user->tokenCan('write:posts')校验 - token 删除要调用
$user->currentAccessToken()->delete()（登出当前设备）或$user->tokens()->delete()（登出所有设备） - 不要把
$token->accessToken当作字符串返回——它是加密后的值，实际要用$token->plainTextToken
CSRF 保护与跨域请求的坑
SPA 调用 Sanctum API 时，首次请求需先 GET /sanctum/csrf-cookie 获取 CSRF token，并将其放入后续请求的 X-XSRF-TOKEN 头中。这个接口必须走 web 中间件，且不能被 api 组包裹。
正确配置（routes/web.php）：
Route::get('/sanctum/csrf-cookie', function () {
return response()->noContent(204);
})->middleware('web');
- 前端 Axios 示例中，需开启
withCredentials: true，否则 Cookie 不发送；同时服务端响应头要有Access-Control-Allow-Credentials: true，且Access-Control-Allow-Origin不能为*（必须指定具体域名） - Laravel 10+ 默认禁用
SameSite=None，若前后端跨协议（HTTP ↔ HTTPS）或跨二级域，需在config/session.php中设置'same_site' => 'none'并确保启用 HTTPS - Chrome 91+ 对第三方 Cookie 更严格，本地开发用
localhost通常没问题，但用127.0.0.1可能触发 SameSite 限制，建议统一用localhost
Sanctum 看似简单，但 Cookie 生命周期、CSRF 流程、跨域策略、token 权限粒度这些点一旦配错，错误信息非常模糊。最常卡住的地方不是代码写法，而是环境配置和前端请求头是否对齐 —— 建议用浏览器开发者工具 Network 面板逐个检查 Cookie、XSRF-TOKEN、Authorization 头是否存在、是否被拦截。
