Laravel Sanctum教程

在现代 Web 开发中，前后端分离的架构已成为主流趋势，而安全可靠的 API 身份认证则是支撑这一架构稳定运行的核心基石。对于使用 Laravel 框架进行后端开发的工程师来说，Laravel Sanctum 提供了一套轻量且功能完善的认证解决方案，它既能为单页面应用、移动应用提供基于 Token 的身份验证，也能支持传统的基于会话的 Web 认证，凭借简单易用的特性被广泛应用于各类项目中。

许多开发者在初次接触 Sanctum 时，常常会将其与 Laravel 自带的 Passport 混淆，其实两者的定位有明显区别。Passport 是一套完整的 OAuth2 服务实现，适合需要第三方应用授权接入的场景，而 Sanctum 则专注于为自建的前端应用、移动客户端提供简单的 Token 认证，配置流程更简洁，性能开销也更低，完全能够满足绝大多数中小型项目的认证需求。

要开始使用 Laravel Sanctum，第一步是通过 Composer 安装扩展包，不过在 Laravel 8 及以上的版本中，Sanctum 已经作为官方推荐的扩展被预置在应用的 composer.json 文件中，开发者只需执行 composer install 就能自动完成安装。安装完成后，需要发布 Sanctum 的配置文件和数据库迁移文件，执行 php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" 命令即可生成对应的配置文件 config/sanctum.php 以及数据库迁移文件，随后运行 php artisan migrate 来创建存储个人访问令牌的数据表。

配置环节的核心在于设置状态域和中间件。对于需要支持会话认证的单页面应用，需要在 sanctum.php 配置文件的 stateful 选项中添加前端应用的域名，这样 Sanctum 才能识别哪些请求应该使用 Laravel 的会话 Cookie 进行认证，从而实现无感知的身份验证。还需要在 app/Http/Kernel.php 文件的 api 中间件组中注册 Sanctum 的中间件，将 EnsureFrontendRequestsAreStateful 类添加到中间件列表的顶部，这一步是实现前后端会话共享的关键，能让来自指定域名的 API 请求自动携带 Laravel 的会话 Cookie。

个人访问令牌是 Sanctum 最常用的功能之一，适合为移动应用、第三方工具提供 API 访问权限。要为用户生成令牌，首先需要在 User 模型中引入 HasApiTokens trait，引入后用户实例就拥有了创建令牌的能力。比如在用户登录接口中，可以调用 $user->createToken('token-name') 方法生成一个新的令牌，该方法会返回一个令牌实例，其中 plainTextToken 属性就是明文形式的令牌值，需要一次性返回给前端并妥善保存，因为后续无法再从数据库中查询到明文令牌。还可以为令牌设置权限，通过 createToken 方法的第二个参数传入权限数组，后续在路由或控制器中可以通过 $user->tokenCan('permission-name') 方法来验证当前令牌是否具备指定权限，实现细粒度的访问控制。

对于单页面应用的认证，Sanctum 提供了基于会话的认证方式，这种方式比传统的 Token 认证更安全，因为认证信息存储在 HttpOnly Cookie 中，能有效防止 XSS 攻击窃取身份凭证。实现这种认证的流程也很简单，前端首先需要调用 /sanctum/csrf-cookie 接口来初始化 CSRF 保护，该接口会设置一个 XSRF-TOKEN Cookie，后续的 POST、PUT 等请求都需要将这个 Cookie 的值作为 X-XSRF-TOKEN 请求头携带。之后前端再调用登录接口，Laravel 会验证用户的账号密码并启动会话，后续的 API 请求就会自动通过会话认证，开发者可以像使用传统 Web 应用一样使用 Auth 门面获取当前登录用户信息，无需额外处理 Token 的解析逻辑。

在实际项目中，令牌的管理同样重要。Sanctum 提供了令牌过期、吊销等功能，开发者可以在 sanctum.php 配置文件中设置 expiration 选项来定义令牌的有效期，单位为分钟，默认情况下令牌是永久有效的。如果需要吊销用户的某个令牌，可以调用 $token->delete() 方法，若是要吊销用户的所有令牌，则可以调用 $user->tokens()->delete()，这在用户修改密码、退出登录等场景中非常实用，能确保旧令牌立即失效，提升账户的安全性。

Sanctum 还支持 SPA 认证与 Token 认证共存，同一套 API 接口可以同时为 Web 端和移动端提供服务，Web 端使用会话认证保证安全性，移动端使用个人访问令牌实现灵活接入，开发者只需通过不同的中间件组来区分认证方式即可，极大地提升了开发效率。

在使用 Sanctum 的过程中，也有一些常见问题需要注意。比如跨域请求导致认证失败，这时候需要检查 config/cors.php 配置文件，确保支持凭据的选项 supports_credentials 设置为 true，同时允许的 Origin 列表中包含前端应用的域名。还有令牌权限验证不生效的问题，大多是因为没有在路由中添加 auth:sanctum 中间件，只有经过该中间件处理的请求，Sanctum 才会自动解析令牌并绑定对应的用户模型，权限验证方法才能正常工作。

Laravel Sanctum 以其轻量、灵活、易上手的特点，成为了 Laravel 生态中 API 认证的首选方案。无论是小型的个人项目，还是中大型的企业级应用，Sanctum 都能提供可靠的认证支持，开发者只需根据项目需求选择合适的认证方式，按照官方文档的指引完成基础配置，就能快速搭建起一套安全稳定的身份认证体系，将更多精力投入到业务逻辑的开发中。随着 Laravel 框架的不断迭代，Sanctum 也在持续优化功能和性能，未来会为开发者带来更优质的使用体验。