Laravel怎么实现API接口鉴权_Laravel Sanctum令牌生成与请求验证【教程】

Sanctum 不生成 JWT，而是用加密字符串作 API 令牌，依赖会话或 Bearer Token 验证；Auth::user() 在 API 路由返回 NULL 主因是未启用 session 中间件或未正确配置 stateful 域名及 cookie 传递。

Sanctum 不生成长期有效的 API 令牌，它依赖于「会话 + Tokenable 模型」的组合实现无状态请求验证；直接调用 createToken() 得到的是加密字符串（不是 JWT），且默认只在当前设备/浏览器有效。

为什么 Auth::user() 在 API 路由里返回 null？

这是最常见的误用起点：Sanctum 的默认行为不自动启用 session 中间件，而 auth:sanctum 中间件只负责从 Authorization: Bearer {token} 或 Cookie 中提取并验证 token —— 但若你没配对使用 stateful 域名或没发带 Cookie 的请求，它就退化为纯 token 验证，此时必须确保请求头含有效 token。

• 检查 config/sanctum.php 中的 stateful 是否包含你的前端域名（如 ['localhost:5173']）
• 确保前端发起请求时携带了 Cookie（credentials: 'include'），否则无法复用 session
• 非 stateful 场景下，必须手动在请求头中传入 Authorization: Bearer {token}
• sanctum 中间件不会自动登录用户，它只设置 Auth::guard('sanctum')->user()；别混用 auth:api 或自定义 guard

createToken() 返回的 token 怎么用？

这个方法返回的是 SanctumPersonalaccessToken 实例，其 plainTextToken 属性才是你要传给前端的明文 token。它本质是服务端生成的随机字符串，存于 personal_access_tokens 表，不加密 payload，也不过期（除非手动 revoke）。

use IlluminateHttpRequest; use IlluminateSupportFacadesAuth;  public function login(Request $request) {     $credentials = $request->only('email', 'password');     if (Auth::attempt($credentials)) {         $user = Auth::user();         // 注意：$token 是 PersonalAccessToken 实例，不是字符串         $token = $user->createToken('api-token');         return response()->json([             'token' => $token->plainTextToken, // ← 必须取这个             'user' => $user         ]);     }     return response()->json(['error' => 'Unauthorized'], 401); }

• 不要把整个 $token 对象 jsON 化返回，它含敏感字段（如 token 字段是哈希值）
• createToken() 第二个参数可传数组定义 abilities，如 ['read', 'write:posts']，后续可用 $user->tokenCan('write:posts') 校验
• 该 token 仅用于 API 请求（auth:sanctum），不能用于登录网页（不触发 session）

如何验证请求是否拥有某权限（abilities）？

Sanctum 的 abilities 是白名单机制，不是 role-based，每次验证都查数据库里的 abilities 字段。它不缓存、不解析 JWT claim，所以性能开销略高于纯 header 解析，但更可控。

// 在控制器中 if (! $request->user()->tokenCan('delete:comments')) {     abort(403); }  // 或在中间件里 if (! $request->user()->currentAccessToken()->can('edit:post')) {     abort(403); }

• abilities 区分大小写，且必须完全匹配（'read' ≠ 'Read'）
• tokenCan() 只对通过 auth:sanctum 认证的用户生效；未认证时 $request->user() 为 null，会报错
• 如果用了 withCookie 或 stateful 模式，$request->user()->currentAccessToken() 可能为 null（因为走的是 session，不是 token）

真正容易被忽略的是：Sanctum 的 token 和 session 是两条路径。你得明确当前请求走哪条——是单页应用用 Bearer token 调 API，还是混合模式下部分接口靠 Cookie 自动鉴权。混用却不校验来源，就会出现 Auth::user() 有时有、有时空的情况。