Laravel Sanctum怎么做API认证_Laravel Sanctum令牌认证SPA和API教程_运维开发

Laravel Sanctum怎么做API认证_Laravel Sanctum令牌认证SPA和API教程

发布时间：2025-11-30

点击量：

Laravel Sanctum 支持 SPA 和 API 认证，1. 安装并发布迁移文件；2. 配置 auth guard 为 sanctum；3. 使用 EnsureFrontendRequestsAreStateful 中间件；4. SPA 通过 web 中间件登录维持 session；5. API 可生成 Personal Access Token；6. 登出时删除 token 或销毁 session，灵活适配多场景。

Laravel Sanctum 提供了一种简单而强大的方式来实现 API 认证，特别适合单页应用（SPA）和移动端接口。它既可以处理传统的 token 认证，也能支持带 session 的 SPA 登录，无需 OAuth 那样复杂的流程。下面带你一步步实现 Laravel Sanctum 的 API 和 SPA 认证。

安装与配置 Sanctum

首先在 Laravel 项目中安装 Sanctum：

composer require laravel/sanctum

发布 Sanctum 的迁移文件并执行：

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

在 app/Http/Kernel.php 中确保 EnsureFrontendRequestsAreStateful 中间件已注册，并且你的前端域名被信任（开发环境可先忽略）。

在 config/auth.php 中设置默认的 guard 为 sanctum 或根据需求配置：

'defaults' => [
    'guard' => 'web',
],
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

启用 Sanctum 中间件

在路由中使用 Sanctum 的认证机制，需要在 app/Http/Kernel.php 的中间件组中添加 \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class 到 api 组，或直接在路由上使用 sanctum.auth。

例如，在 routes/api.php 中：

use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });
});

为 SPA 实现登录认证

如果你是 SPA（如 Vue + Laravel），用户通过账号密码登录获取 session，而不是 token。此时不需要手动创建 token，而是走传统的登录流程。

创建登录接口：

// routes/api.php
Route::post('/login', function (Request $request) {
    $credentials = $request->only('email', 'password');

    if (Auth::attempt($credentials)) {
        return response()->json(['message' => '登录成功']);
    }

    return response()->json(['message' => '凭证错误'], 401);
});

确保登录接口在 web 中间件下才能维持 session，建议将登录、登出等放到 routes/web.php，或手动加上 web 中间件。

修改为：

// web.php
Route::post('/login', function (Request $request) {
    $credentials = $request->only('email', 'password');

    if (Auth::attempt($credentials)) {
        return response()->json(['message' => '登录成功']);
    }

    return response()->json(['message' => '凭证错误'], 401);
})->middleware('web');

前端请求时需携带 Cookie（浏览器自动处理），后续请求带上 XSRF-TOKEN 防止 CSRF。Laravel 自动设置 XSRF-TOKEN cookie，前端 Axios 可自动发送：

axios.defaults.withCredentials = true;

为 API 应用生成个人访问令牌

如果客户端是移动端或第三方应用，推荐使用 Personal Access Tokens。用户登录后创建 token 返回给客户端，后续请求携带 token 即可。

示例：用户登录并返回 token

// 控制器方法
public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (!Auth::attempt($request->only('email', 'password'))) {
        return response()->json(['message' => '登录失败'], 401);
    }

    $user = $request->user();
    $token = $user->createToken('api-token')->plainTextToken;

    return response()->json(['token' => $token]);
}

客户端之后在请求头中携带 token：

Authorization: Bearer 1|abcdef123456789...

该 token 存储在 personal_access_tokens 表中，可通过 $user->tokens() 管理。

登出与 Token 注销

对于 token 登录，登出即删除当前 token：

public function logout(Request $request)
{
    $request->user()->currentAccessToken()->delete();

    return response()->json(['message' => '已登出']);
}

如果是 SPA 使用 session 登录，登出调用 Auth::logout() 并清除 session：

public function logout(Request $request)
{
    Auth::logout();
    $request->session()->invalidate();
    $request->session()->regenerateToken();

    return response()->json(['message' => '已退出']);
}

基本上就这些。Laravel Sanctum 的优势在于灵活适配不同场景，你可以同时支持 SPA 的 session 登录和 API 的 token 认证，按需选择即可。不复杂但容易忽略中间件和跨域配置，调试时注意检查 cookie、CORS 和认证 guard 设置。

上一篇：Laravel如何实现延迟加载_Eloquent Lazy

下一篇：Laravel Inertia.js入门教程_Laravel