Laravel怎么实现API认证_Laravel Sanctum轻量级认证方案【源码】

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="LaravelSanctumSanctumServiceProvider"

这会生成 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 IlluminateHttpRequest;  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 头是否存在、是否被拦截。