Laravel Sanctum 用于 PHP：API 令牌和 SPA 认证完整指南

1. 什么是 Sanctum 以及为什么需要它

Laravel Sanctum 是一个轻量级的认证库，适用于 PHP 框架 Laravel，旨在管理 API 令牌和单页应用程序 (SPA)。由 Taylor Otwell 和 Laravel 团队开发，Sanctum 提供了一种简单而强大的方式来保护 API 路由，使开发人员无需像 Passport (OAuth2) 等更重量级解决方案那样进行复杂配置，即可快速实现认证。

Sanctum 的主要任务是解决现代 Web 开发中的两个关键问题：为与后端运行在同一域上的 SPA（单页应用程序）进行认证，以及为移动应用程序或第三方服务颁发 API 令牌。与 Passport 不同，Sanctum 不使用完整的 OAuth2 协议，这使其成为不需要复杂访问委托系统的项目的理想选择。它使用 Laravel 会话进行 SPA 认证，并使用基于 HMAC 的简单令牌进行 API 认证。

该库包含在 Laravel 8 及更高版本的标准发行版中，使其“开箱即用”。Sanctum 对初创公司、小型团队以及重视开发速度和最小依赖项的项目特别有用。它自动管理令牌过期时间，支持“能力”（abilities）以进行精细的权限控制，并且可以轻松与 Laravel Fortify、Breeze 或 Jetstream 集成。

2. 安装

Laravel Sanctum 通过 Composer（PHP 的标准包管理器）安装。请确保您已安装 PHP 8.0 或更高版本以及 Laravel 8.x/9.x/10.x/11.x。

确切的安装命令：

composer require laravel/sanctum

安装后，需要发布配置文件和数据库迁移：

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

然后，运行迁移以创建 personal_access_tokens 表：

php artisan migrate

对于 SPA 认证，还需要将中间件 EnsureFrontendRequestsAreStateful 添加到 HTTP 内核（文件 app/Http/Kernel.php）：

'api' => [\n    \\Laravel\\Sanctum\\Http\\Middleware\\EnsureFrontendRequestsAreStateful::class,\n    'throttle:api',\n    \\Illuminate\\Routing\\Middleware\\SubstituteBindings::class,\n],

另外，在 .env 文件中指定您的 SPA 域名：

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. 快速入门 — 最小工作示例

让我们看一个颁发 API 令牌和保护路由的最小示例。

步骤 1：User 模型

在 App\\Models\\User 模型中使用 HasApiTokens trait：

validate([\n        'email' => 'required|email',\n        'password' => 'required',\n    ]);\n\n    if (auth()->attempt($credentials)) {\n        $user = auth()->user();\n        $token = $user->createToken('api-token')->plainTextToken;\n        \n        ret