LaravelPassport还是Sanctum

wen PHP项目 2026-07-07 4

Laravel Passport vs Sanctum：2025年API认证终极指南（附选型问答）

📖 目录导读

核心差异：两大认证系统的基因对比
Passport深度解析：OAuth2的全量武器库
Sanctum优势：轻量级Token + SPA完美伴侣
场景对决：什么项目该选谁？（含实战代码）
高频问答：开发者最纠结的5个问题

核心差异：两大认证系统的基因对比

在Laravel生态中，Passport 与 Sanctum 常被误认为“高端与低配”的二元选择，但根据2024年Laravel官方社区统计，40%的Passport项目实际上可以用Sanctum替代，而25%的Sanctum项目因忽略OAuth2需求被迫重构。

LaravelPassport还是Sanctum

基因图谱

维度	Passport	Sanctum
底层协议	OAuth2完整实现（RFC 6749）	基于Token的轻量级方案
令牌类型	访问令牌 + 刷新令牌 + 授权码	API令牌 + SPA会话Cookie
脚手架复杂度	需迁移数据库（6张表）	单表 `personal_access_tokens`
第三方客户端	原生支持（微信/支付宝登录等）	需手动实现
Laravel默认推荐	x之前主流	x之后官方首选

关键结论：不要用“新旧”判断，而要用 “是否需要第三方授权” 作为首要筛选条件。

Passport深度解析：OAuth2的全量武器库

适用场景矩阵

✅ 多客户端应用（iOS + Web + 第三方）
✅ 需要细粒度权限作用域（Scope）
✅ 对接企业级SSO系统（如OAuth2.0兼容的ADFS）
❌ 单页面应用（SPA）的常规登录

隐藏痛点（多数教程不会说）

// 示例：Passport默认令牌过期时间极短
// 在AuthServiceProvider中需手动调整
Passport::tokensExpireIn(now()->addDays(15));
Passport::refreshTokensExpireIn(now()->addDays(30));

安全陷阱：未及时配置 Passport::cookie() 会导致CSRF漏洞,社区已出现多起案例。

性能对比数据

指标	Passport	Sanctum
单次认证数据库查询	3次（令牌表+客户端表+作用域）	1次
并发100请求下P99延迟	240ms	87ms

Sanctu的优势：轻量级Token + SPA完美体验

为何Sanctum成为Laravel 11默认选择？

零配置API开发：只读 Sanctum::actingAs($user) 即可模拟认证
SPA原生支持：通过 EnsureFrontendRequestsAreStateful 中间件自动处理CSRF
令牌能力继承：支持精细的权限控制，但默认不作用域

实战案例：移动端+管理后台混合场景

// 给用户生成永不过期的API令牌（适合服务器到服务器）
$token = $user->createToken('cron-job-token', ['read:reports'])->plainTextToken;
// 而Passport需生成code+state+redirect流程
$query = http_build_query([
    'client_id' => 3,
    'redirect_uri' => 'your-app.com/callback',
    'response_type' => 'code',
    'scope' => 'read-reports',
]);

注意：Sanctum的永不过期令牌是双刃剑——若遭泄露，需到 personal_access_tokens 表手动删除。

场景对决：什么项目该选谁？

决策流程图

项目需要OAuth2授权吗？
├─ 是 → Passport
└─ 否 → 是否需要第三方登录？
   ├─ 是 → Passport（或Socialite+Passport组合）
   └─ 否 → 是否为纯SPA/移动端？
      ├─ 是 → Sanctum
      └─ 否 → 检查令牌过期时间：
         ├─ 需要刷新令牌 → Passport
         └─ 不需要 → Sanctum

3个典型错误案例

电商平台选型错误：用户用微信登录（需OAuth2）却使用Sanctum → 被迫手动实现OAuth2流程，导致代码量翻倍
内部管理系统：仅服务内部员工却使用Passport → 数据库多出6张无用表，维护成本激增
游戏API：需15分钟短令牌 + 离线令牌刷新 → Sanctum无法原生支持刷新令牌，必须用Passport

高频问答：开发者最纠结的5个问题

Q1：Sanctum的API令牌和Passport的个人访问令牌有什么区别？

本质相同：都是Bearer Token，不同在于：

Sanctum用Laravel自带的哈希加密令牌，Passport用公钥/私钥签名。
性能差异：Sanctum每次请求查数据库验证令牌，Passport依赖JWT无状态验证（但需维护密钥轮换）。

Q2：能否混合使用Passport和Sanctum？

可以，但极少必要。

第三方客户端 → Passport
移动端App → Sanctum
需在 auth.php 配置两个守卫：
```
'guards' => [
  'api-passport' => ['driver' => 'passport'],
  'api-sanctum' => ['driver' => 'sanctum'],
]
```
警告：两个系统会共用 users 表，但 auth:api-passport 和 auth:api-sanctum 中间件不能混用在同一路由组。

Q3：Sanctum支持社交登录吗？

不支持原生，需借助 laravel/socialite 获取社交账号的邮箱，再手动调用 $user->createToken()，而Passport可直接通过social grant实现。

Q4：哪个更适合微服务架构？

推荐Passport，因微服务间需要用JWT令牌进行无状态通信，且需独立的授权服务器（授权码模式）,Sanctum的数据库验证在微服务场景下会变成性能瓶颈。

Q5：Laravel 11后，官方是否放弃了Passport？

没有放弃，官方文档依然保留完整Passport章节，只是默认安装移除，Laravel创始人Taylor Otwell在2024年Laracon明确表示：“Passport是为高度定制化OAuth2场景而生，而Sanctum是90%场景的默认最优解。”

最终选择清单

选择 Sanctum 的5个信号：
✅ 仅自有前端（SPA/移动端）
✅ 无需第三方授权
✅ 项目启动需快速交付
✅ 团队对OAuth2不熟悉
✅ 服务器成本敏感
选择 Passport 的5个信号：
✅ 需要开放API给第三方
✅ 需细粒度作用域（scope:read-only）
✅ 对接企业级认证系统
✅ 令牌需无状态验证（性能优先）
✅ 需要完善的刷新令牌机制

决策金句：当你不确定时，先用 php artisan install:api（安装Sanctum），未来遇到第三方需求时再迁移到Passport——Laravel官方提供了两条路径的无痛升级指南。